glStencilFunc 函式

glStencilFunc 函式會設定樣板測試的函式和參考值。

語法

void WINAPI glStencilFunc(
   GLenum func,
   GLint  ref,
   GLuint mask
);

參數

func

測試函式。 下列八個令牌有效。

值	意義
GL_NEVER	一律失敗。
GL_LESS	通過 if （ref & mask） < （樣板 和 遮罩）。
GL_LEQUAL	傳遞 if （ref & mask） = （樣板 和 遮罩）。
GL_GREATER	通過 if （ref & mask） > （樣板 和 遮罩）。
GL_GEQUAL	傳遞 if （ref & mask） = （樣板 和 遮罩）。
GL_EQUAL	傳遞 if （ref & mask） = （樣板 和 遮罩）。
GL_NOTEQUAL	透過 if （ref & mask） ？ （樣板 和 遮罩）。
GL_ALWAYS	一律通過。

ref

樣板測試的參考值。 ref 參數會夾在範圍 [0， 2n 1]，其中 n 是樣板緩衝區中的位平面數目。

面具

當測試完成時，具有參考值和預存樣板值的遮罩。

傳回值

此函式不會傳回值。

錯誤碼

glGetError 函式可以擷取下列錯誤碼。

名稱	意義
GL_INVALID_ENUM	func 不是八個公認的值之一。
GL_INVALID_OPERATION	在 glBegin 呼叫與 glEnd 的對應呼叫之間呼叫函式。

備註

Stenciling，例如 z 緩衝處理，會啟用和停用以每像素為基礎的繪圖。 您可以使用 OpenGL 繪圖基本類型繪製到樣板平面，然後使用樣板平面來遮罩螢幕的部分，來轉譯幾何和影像。 Stenciling 通常用於多重通道轉譯演算法，以達到特殊效果，例如裝飾、大綱和建設性實心幾何轉譯。

樣板測試會根據參考值與樣板緩衝區中值之間的比較結果，有條件地排除圖元。 此測試是由 glEnable 和 glDisable 搭配自變數GL_STENCIL_TEST啟用。 根據樣板測試結果所採取的動作會以 glStencilOp 指定。

func 參數是決定樣板比較函式的符號常數。 它接受上述八個值之一。 ref 參數是樣板比較中使用的整數參考值。 它夾在範圍 [0， 2n 1]，其中 n 是樣板緩衝區中的位平面數目。 mask 參數是以參考值和預存樣板值來位 ANDed，而 ANDed 值則參與比較。

如果樣板代表儲存在對應樣板緩衝區位置中的值，上述清單會顯示 func 可以指定之每個比較函式的效果。 只有在比較成功時，才會將像素傳遞至點陣化程式的下一個階段（請參閱 glStencilOp）。 所有測試都會將樣板值視為範圍 [0， 2n 1] 中的無符號整數，其中 n 是樣板緩衝區中的位平面數目。

一開始，樣板測試會停用。 如果沒有樣板緩衝區，則不會進行樣板修改，而且樣板測試一律通過。

下列函式會擷取與 glStencilFunc 相關的資訊：

glGet 與自變數GL_STENCIL_FUNC

glGet 與自變數GL_STENCIL_VALUE_MASK

glGet 與自變數GL_STENCIL_REF

具有自變數的 glGet GL_STENCIL_BITS

glIsEnabled 搭配自變數GL_STENCIL_TEST

需求

需求	值
最低支援的用戶端	Windows 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
頁首	Gl.h
程式庫	Opengl32.lib
DLL	Opengl32.dll

另請參閱

glAlphaFunc

glBegin

glBlendFunc

glDepthFunc

glEnable

glEnd

glIsEnabled

glLogicOp

glStencilOp