Depth State

## Depth State Depth State — Functions for describing the depth testing state of your GPU. |

## Synopsis

                        CoglDepthState;
    enum                CoglDepthTestFunction;
    void                cogl_depth_state_init               (CoglDepthState *state);
    void                cogl_depth_state_set_test_enabled   (CoglDepthState *state,
                                                             CoglBool enable);
    CoglBool            cogl_depth_state_get_test_enabled   (CoglDepthState *state);
    void                cogl_depth_state_set_test_function  (CoglDepthState *state,
                                                             CoglDepthTestFunction function);
    CoglDepthTestFunction cogl_depth_state_get_test_function
                                                            (CoglDepthState *state);
    void                cogl_depth_state_set_write_enabled  (CoglDepthState *state,
                                                             CoglBool enable);
    CoglBool            cogl_depth_state_get_write_enabled  (CoglDepthState *state);
    void                cogl_depth_state_set_range          (CoglDepthState *state,
                                                             float near_val,
                                                             float far_val);
    void                cogl_depth_state_get_range          (CoglDepthState *state,
                                                             float *near_val,
                                                             float *far_val);

## Description

## Details

### CoglDepthState

    typedef struct {
    } CoglDepthState;

Since 2.0

### enum CoglDepthTestFunction

    typedef enum {
      COGL_DEPTH_TEST_FUNCTION_NEVER    = 0x0200,
      COGL_DEPTH_TEST_FUNCTION_LESS     = 0x0201,
      COGL_DEPTH_TEST_FUNCTION_EQUAL    = 0x0202,
      COGL_DEPTH_TEST_FUNCTION_LEQUAL   = 0x0203,
      COGL_DEPTH_TEST_FUNCTION_GREATER  = 0x0204,
      COGL_DEPTH_TEST_FUNCTION_NOTEQUAL = 0x0205,
      COGL_DEPTH_TEST_FUNCTION_GEQUAL   = 0x0206,
      COGL_DEPTH_TEST_FUNCTION_ALWAYS   = 0x0207
    } CoglDepthTestFunction;

When using depth testing one of these functions is used to compare the depth of an incoming fragment against the depth value currently stored in the depth buffer. The function is changed using `cogl_depth_state_set_test_function()`.

The test is only done when depth testing is explicitly enabled. (See `cogl_depth_state_set_test_enabled()`)

`COGL_DEPTH_TEST_FUNCTION_NEVER` | Never passes.
`COGL_DEPTH_TEST_FUNCTION_LESS` | Passes if the fragment's depth value is less than the value currently in the depth buffer.
`COGL_DEPTH_TEST_FUNCTION_EQUAL` | Passes if the fragment's depth value is equal to the value currently in the depth buffer.
`COGL_DEPTH_TEST_FUNCTION_LEQUAL` | Passes if the fragment's depth value is less or equal to the value currently in the depth buffer.
`COGL_DEPTH_TEST_FUNCTION_GREATER` | Passes if the fragment's depth value is greater than the value currently in the depth buffer.
`COGL_DEPTH_TEST_FUNCTION_NOTEQUAL` | Passes if the fragment's depth value is not equal to the value currently in the depth buffer.
`COGL_DEPTH_TEST_FUNCTION_GEQUAL` | Passes if the fragment's depth value greater than or equal to the value currently in the depth buffer.
`COGL_DEPTH_TEST_FUNCTION_ALWAYS` | Always passes.

### cogl_depth_state_init ()

    void                cogl_depth_state_init               (CoglDepthState *state);

Initializes the members of `state` to their default values.

You should never pass an un initialized CoglDepthState structure to `cogl_pipeline_set_depth_state()`.

`state` : | A CoglDepthState struct

Since 2.0

Stability Level: Unstable

### cogl_depth_state_set_test_enabled ()

    void                cogl_depth_state_set_test_enabled   (CoglDepthState *state,
                                                             CoglBool enable);

Enables or disables depth testing according to the value of `enable`.

If depth testing is enable then the CoglDepthTestFunction set using `cogl_depth_state_set_test_function()` us used to evaluate the depth value of incoming fragments against the corresponding value stored in the current depth buffer, and if the test passes then the fragments depth value is used to update the depth buffer. (unless you have disabled depth writing via `cogl_depth_state_set_write_enabled()`)

By default depth testing is disabled.

NB: this won't directly affect the state of the GPU. You have to then set the state on a CoglPipeline using `cogl_pipeline_set_depth_state()`

`state` : | A CoglDepthState struct
`enable` : | The enable state you want

Since 2.0

Stability Level: Unstable

### cogl_depth_state_get_test_enabled ()

    CoglBool            cogl_depth_state_get_test_enabled   (CoglDepthState *state);

Gets the current depth test enabled state as previously set by `cogl_depth_state_set_test_enabled()`.

`state` : | A CoglDepthState struct
Returns : | The pipeline's current depth test enabled state.

Since 2.0

Stability Level: Unstable

### cogl_depth_state_set_test_function ()

    void                cogl_depth_state_set_test_function  (CoglDepthState *state,
                                                             CoglDepthTestFunction function);

Sets the CoglDepthTestFunction used to compare the depth value of an incoming fragment against the corresponding value in the current depth buffer.

By default the depth test function is `COGL_DEPTH_TEST_FUNCTION_LESS`

NB: this won't directly affect the state of the GPU. You have to then set the state on a CoglPipeline using `cogl_pipeline_set_depth_state()`

`state` : | A CoglDepthState struct
`function` : | The CoglDepthTestFunction to set

Since 2.0

Stability Level: Unstable

### cogl_depth_state_get_test_function ()

    CoglDepthTestFunction cogl_depth_state_get_test_function
                                                            (CoglDepthState *state);

Gets the current depth test enable state as previously set via `cogl_depth_state_set_test_enabled()`.

`state` : | A CoglDepthState struct
Returns : | The current depth test enable state.

Since 2.0

Stability Level: Unstable

### cogl_depth_state_set_write_enabled ()

    void                cogl_depth_state_set_write_enabled  (CoglDepthState *state,
                                                             CoglBool enable);

Enables or disables depth buffer writing according to the value of `enable`. Normally when depth testing is enabled and the comparison between a fragment's depth value and the corresponding depth buffer value passes then the fragment's depth is written to the depth buffer unless writing is disabled here.

By default depth writing is enabled

NB: this won't directly affect the state of the GPU. You have to then set the state on a CoglPipeline using `cogl_pipeline_set_depth_state()`

`state` : | A CoglDepthState struct
`enable` : | The enable state you want

Since 2.0

Stability Level: Unstable

### cogl_depth_state_get_write_enabled ()

    CoglBool            cogl_depth_state_get_write_enabled  (CoglDepthState *state);

Gets the depth writing enable state as set by the corresponding `cogl_depth_state_set_write_enabled()`.

`state` : | A CoglDepthState struct
Returns : | The current depth writing enable state

Since 2.0

Stability Level: Unstable

### cogl_depth_state_set_range ()

    void                cogl_depth_state_set_range          (CoglDepthState *state,
                                                             float near_val,
                                                             float far_val);

Sets the range to map depth values in normalized device coordinates to before writing out to a depth buffer.

After your geometry has be transformed, clipped and had perspective division applied placing it in normalized device coordinates all depth values between the near and far z clipping planes are in the range -1 to 1. Before writing any depth value to the depth buffer though the value is mapped into the range [0, 1].

With this function you can change the range which depth values are mapped too although the range must still lye within the range [0, 1].

If your driver does not support this feature (for example you are using GLES 1 drivers) then if you don't use the default range values you will get an error reported when calling `cogl_pipeline_set_depth_state()`. You can check ahead of time for the `COGL_FEATURE_ID_DEPTH_RANGE` feature with `cogl_has_feature()` to know if this function will succeed.

By default normalized device coordinate depth values are mapped to the full range of depth buffer values, [0, 1].

NB: this won't directly affect the state of the GPU. You have to then set the state on a CoglPipeline using `cogl_pipeline_set_depth_state()`.

`state` : | A CoglDepthState object
`near_val` : | The near component of the desired depth range which will be clamped to the range [0, 1]
`far_val` : | The far component of the desired depth range which will be clamped to the range [0, 1]

Since 2.0

Stability Level: Unstable

### cogl_depth_state_get_range ()

    void                cogl_depth_state_get_range          (CoglDepthState *state,
                                                             float *near_val,
                                                             float *far_val);

Gets the current range to which normalized depth values are mapped before writing to the depth buffer. This corresponds to the range set with `cogl_depth_state_set_range()`.

`state` : | A CoglDepthState object
`near_val` : | A pointer to store the near component of the depth range
`far_val` : | A pointer to store the far component of the depth range

Since 2.0

Stability Level: Unstable