Skip to content

Commit 0497ae9

Browse files
akien-mgaakien-mga
committed
Merge pull request #80710 from apples/7174-apples-stencil
Add stencil support to spatial materials
2 parents 2ee5d28 + d674c9e commit 0497ae9

29 files changed

+1515
-158
lines changed

‎doc/classes/BaseMaterial3D.xml‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -159,6 +159,10 @@
159159
<member name="depth_draw_mode" type="int" setter="set_depth_draw_mode" getter="get_depth_draw_mode" enum="BaseMaterial3D.DepthDrawMode" default="0">
160160
Determines when depth rendering takes place. See also [member transparency].
161161
</member>
162+
<member name="depth_test" type="int" setter="set_depth_test" getter="get_depth_test" enum="BaseMaterial3D.DepthTest" default="0" experimental="May be affected by future rendering pipeline changes.">
163+
Determines which comparison operator is used when testing depth. See [enum DepthTest].
164+
[b]Note:[/b] Changing [member depth_test] to a non-default value only has a visible effect when used on a transparent material, or a material that has [member depth_draw_mode] set to [constant DEPTH_DRAW_DISABLED].
165+
</member>
162166
<member name="detail_albedo" type="Texture2D" setter="set_texture" getter="get_texture">
163167
Texture that specifies the color of the detail overlay. [member detail_albedo]'s alpha channel is used as a mask, even when the material is opaque. To use a dedicated texture as a mask, see [member detail_mask].
164168
[b]Note:[/b] [member detail_albedo] is [i]not[/i] modulated by [member albedo_color].
@@ -374,6 +378,24 @@
374378
The method for rendering the specular blob.
375379
[b]Note:[/b] [member specular_mode] only applies to the specular blob. It does not affect specular reflections from the sky, screen-space reflections, [VoxelGI], SDFGI or [ReflectionProbe]s. To disable reflections from these sources as well, set [member metallic_specular] to [code]0.0[/code] instead.
376380
</member>
381+
<member name="stencil_color" type="Color" setter="set_stencil_effect_color" getter="get_stencil_effect_color" default="Color(0, 0, 0, 1)" experimental="May be affected by future rendering pipeline changes.">
382+
The primary color of the stencil effect.
383+
</member>
384+
<member name="stencil_compare" type="int" setter="set_stencil_compare" getter="get_stencil_compare" enum="BaseMaterial3D.StencilCompare" default="0" experimental="May be affected by future rendering pipeline changes.">
385+
The comparison operator to use for stencil masking operations. See [enum StencilCompare].
386+
</member>
387+
<member name="stencil_flags" type="int" setter="set_stencil_flags" getter="get_stencil_flags" default="0" experimental="May be affected by future rendering pipeline changes.">
388+
The flags dictating how the stencil operation behaves. See [enum StencilFlags].
389+
</member>
390+
<member name="stencil_mode" type="int" setter="set_stencil_mode" getter="get_stencil_mode" enum="BaseMaterial3D.StencilMode" default="0" experimental="May be affected by future rendering pipeline changes.">
391+
The stencil effect mode. See [enum StencilMode].
392+
</member>
393+
<member name="stencil_outline_thickness" type="float" setter="set_stencil_effect_outline_thickness" getter="get_stencil_effect_outline_thickness" default="0.01" experimental="May be affected by future rendering pipeline changes.">
394+
The outline thickness for [constant STENCIL_MODE_OUTLINE].
395+
</member>
396+
<member name="stencil_reference" type="int" setter="set_stencil_reference" getter="get_stencil_reference" default="1" experimental="May be affected by future rendering pipeline changes.">
397+
The stencil reference value (0-255). Typically a power of 2.
398+
</member>
377399
<member name="subsurf_scatter_enabled" type="bool" setter="set_feature" getter="get_feature" default="false">
378400
If [code]true[/code], subsurface scattering is enabled. Emulates light that penetrates an object's surface, is scattered, and then emerges. Subsurface scattering quality is controlled by [member ProjectSettings.rendering/environment/subsurface_scattering/subsurface_scattering_quality].
379401
</member>
@@ -661,6 +683,12 @@
661683
<constant name="DEPTH_DRAW_DISABLED" value="2" enum="DepthDrawMode">
662684
Objects will not write their depth to the depth buffer, even during the depth prepass (if enabled).
663685
</constant>
686+
<constant name="DEPTH_TEST_DEFAULT" value="0" enum="DepthTest">
687+
Depth test will discard the pixel if it is behind other pixels.
688+
</constant>
689+
<constant name="DEPTH_TEST_INVERTED" value="1" enum="DepthTest">
690+
Depth test will discard the pixel if it is in front of other pixels. Useful for stencil effects.
691+
</constant>
664692
<constant name="CULL_BACK" value="0" enum="CullMode">
665693
Default cull mode. The back of the object is culled when not visible. Back face triangles will be culled when facing the camera. This results in only the front side of triangles being drawn. For closed-surface meshes, this means that only the exterior of the mesh will be visible.
666694
</constant>
@@ -818,5 +846,49 @@
818846
<constant name="DISTANCE_FADE_OBJECT_DITHER" value="3" enum="DistanceFadeMode">
819847
Smoothly fades the object out based on the object's distance from the camera using a dithering approach. Dithering discards pixels based on a set pattern to smoothly fade without enabling transparency. On certain hardware, this can be faster than [constant DISTANCE_FADE_PIXEL_ALPHA] and [constant DISTANCE_FADE_PIXEL_DITHER].
820848
</constant>
849+
<constant name="STENCIL_MODE_DISABLED" value="0" enum="StencilMode">
850+
Disables stencil operations.
851+
</constant>
852+
<constant name="STENCIL_MODE_OUTLINE" value="1" enum="StencilMode">
853+
Stencil preset which applies an outline to the object.
854+
[b]Note:[/b] Requires a [member Material.next_pass] material which will be automatically applied. Any manual changes made to [member Material.next_pass] will be lost when the stencil properties are modified or the scene is reloaded. To safely apply a [member Material.next_pass] material on a material that uses stencil presets, use [member GeometryInstance3D.material_overlay] instead.
855+
</constant>
856+
<constant name="STENCIL_MODE_XRAY" value="2" enum="StencilMode">
857+
Stencil preset which shows a silhouette of the object behind walls.
858+
[b]Note:[/b] Requires a [member Material.next_pass] material which will be automatically applied. Any manual changes made to [member Material.next_pass] will be lost when the stencil properties are modified or the scene is reloaded. To safely apply a [member Material.next_pass] material on a material that uses stencil presets, use [member GeometryInstance3D.material_overlay] instead.
859+
</constant>
860+
<constant name="STENCIL_MODE_CUSTOM" value="3" enum="StencilMode">
861+
Enables stencil operations without a preset.
862+
</constant>
863+
<constant name="STENCIL_FLAG_READ" value="1" enum="StencilFlags">
864+
The material will only be rendered where it passes a stencil comparison with existing stencil buffer values. See [enum StencilCompare].
865+
</constant>
866+
<constant name="STENCIL_FLAG_WRITE" value="2" enum="StencilFlags">
867+
The material will write the reference value to the stencil buffer where it passes the depth test.
868+
</constant>
869+
<constant name="STENCIL_FLAG_WRITE_DEPTH_FAIL" value="4" enum="StencilFlags">
870+
The material will write the reference value to the stencil buffer where it fails the depth test.
871+
</constant>
872+
<constant name="STENCIL_COMPARE_ALWAYS" value="0" enum="StencilCompare">
873+
Always passes the stencil test.
874+
</constant>
875+
<constant name="STENCIL_COMPARE_LESS" value="1" enum="StencilCompare">
876+
Passes the stencil test when the reference value is less than the existing stencil value.
877+
</constant>
878+
<constant name="STENCIL_COMPARE_EQUAL" value="2" enum="StencilCompare">
879+
Passes the stencil test when the reference value is equal to the existing stencil value.
880+
</constant>
881+
<constant name="STENCIL_COMPARE_LESS_OR_EQUAL" value="3" enum="StencilCompare">
882+
Passes the stencil test when the reference value is less than or equal to the existing stencil value.
883+
</constant>
884+
<constant name="STENCIL_COMPARE_GREATER" value="4" enum="StencilCompare">
885+
Passes the stencil test when the reference value is greater than the existing stencil value.
886+
</constant>
887+
<constant name="STENCIL_COMPARE_NOT_EQUAL" value="5" enum="StencilCompare">
888+
Passes the stencil test when the reference value is not equal to the existing stencil value.
889+
</constant>
890+
<constant name="STENCIL_COMPARE_GREATER_OR_EQUAL" value="6" enum="StencilCompare">
891+
Passes the stencil test when the reference value is greater than or equal to the existing stencil value.
892+
</constant>
821893
</constants>
822894
</class>

‎drivers/gles3/rasterizer_gles3.cpp‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -138,6 +138,10 @@ void RasterizerGLES3::clear_depth(float p_depth) {
138138
#endif // GLES_API_ENABLED
139139
}
140140

141+
void RasterizerGLES3::clear_stencil(int32_t p_stencil) {
142+
glClearStencil(p_stencil);
143+
}
144+
141145
#ifdef CAN_DEBUG
142146
static void GLAPIENTRY _gl_debug_print(GLenum source, GLenum type, GLuint id, GLenum severity, GLsizei length, const GLchar *message, const GLvoid *userParam) {
143147
// These are ultimately annoying, so removing for now.

‎drivers/gles3/rasterizer_gles3.h‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -116,6 +116,7 @@ class RasterizerGLES3 : public RendererCompositor {
116116

117117
static bool is_gles_over_gl() { return gles_over_gl; }
118118
static void clear_depth(float p_depth);
119+
static void clear_stencil(int32_t p_stencil);
119120

120121
static void make_current(bool p_gles_over_gl) {
121122
gles_over_gl = p_gles_over_gl;

0 commit comments

Comments
 (0)