1 /*---------------------------------------------------------------------------*
2 
3   Copyright (C) Nintendo.  All rights reserved.
4 
5   These coded instructions, statements, and computer programs contain
6   proprietary information of Nintendo of America Inc. and/or Nintendo
7   Company Ltd., and are protected by Federal copyright law.  They may
8   not be disclosed to third parties or copied or duplicated in any form,
9   in whole or in part, without the prior written consent of Nintendo.
10 
11  *---------------------------------------------------------------------------*/
12 
13 // gx2RenderState.h
14 //
15 // Declares gx2RenderState-related types & functions for gx2 library.
16 
17 #ifndef _CAFE_GX2_RENDERSTATE_H_
18 #define _CAFE_GX2_RENDERSTATE_H_
19 
20 #ifdef __cplusplus
21 extern "C"
22 {
23 #endif // __cplusplus
24 
25 /// @addtogroup GX2RenderStateGroup
26 /// @{
27 /// @addtogroup GX2RenderStateDepthStencilGroup
28 /// @{
29 
30 // -----------------
31 // GX2RenderState.h
32 
33 /// \brief Sets depth & stencil controls.
34 ///
35 /// \param depthEnable       enables depth testing. if depthEnable is false,
36 ///                          then all depth operations are disabled
37 ///                          (depthWriteEnable is ignored), and color writes
38 ///                          will not be affected by the depth test.
39 /// \param depthWriteEnable  enables writing to the depth buffer
40 ///                          if the depth test passes.
41 /// \param depthFunc         function that compares the depth at each sample
42 ///                          in the fragment to the destination depth at the
43 ///                          corresponding sample point.
44 /// \param stencilTestEnable enables stencil testing. if disabled, all pixels
45 ///                          pass the stencil test. If there is no stencil
46 ///                          buffer this is treated as disabled.
47 /// \param backStencilEnable if false, forces all quads to be stencil tested
48 ///                          as frontface quads.
49 /// \param frontStencilFunc  function that compares stencil reference value to
50 ///                          the destination stencil value for frontface quads.
51 /// \param frontStencilZPass stencil operation for frontface quads if the
52 ///                          stencil and depth functions both pass.
53 /// \param frontStencilZFail stencil operation for frontface quads if the
54 ///                          stencil function passes and the depth function
55 ///                          fails.
56 /// \param frontStencilFail  stencil operation for frontface quads if the
57 ///                          stencil function fails.
58 /// \param backStencilFunc   function that compares backface stencil reference
59 ///                          value to the destination stencil value for
60 ///                          backface quads.
61 /// \param backStencilZPass  stencil operation for backface quads if the
62 ///                             stencil and depth functions both pass.
63 /// \param backStencilZFail  stencil operation for backface quads if the
64 ///                          stencil function passes and the depth function
65 ///                          fails.
66 /// \param backStencilFail   stencil operation for backface quads if the stencil
67 ///                          function fails.
68 ///
69 /// \donotcall \gx2_typical \enddonotcall
70 ///
71 /// \writesgpu
72 /// \alwayswritesgpu
73 ///
74 void GX2API GX2SetDepthStencilControl(GX2Boolean depthEnable,
75                                       GX2Boolean depthWriteEnable,
76                                       GX2CompareFunction depthFunc,
77                                       GX2Boolean stencilTestEnable,
78                                       GX2Boolean backStencilEnable,
79 
80                                       GX2CompareFunction frontStencilFunc,
81                                       GX2StencilFunction frontStencilZPass,
82                                       GX2StencilFunction frontStencilZFail,
83                                       GX2StencilFunction frontStencilFail,
84 
85                                       GX2CompareFunction backStencilFunc,
86                                       GX2StencilFunction backStencilZPass,
87                                       GX2StencilFunction backStencilZFail,
88                                       GX2StencilFunction backStencilFail);
89 
90 /// \brief An alternate API to set depth-buffer controls and disable stencil.
91 ///
92 /// This function may be used to set the depth-buffer controls when stencil
93 /// is not present or not needed.  It always disables the stencil functions.
94 /// If stencil control is needed, use \ref GX2SetDepthStencilControl.
95 ///
96 /// \note *Disables stencil*, sets depth control as specified.
97 ///
98 /// \param depthEnable       enables depth testing. if depthEnable is false,
99 ///                          then all depth operations are disabled
100 ///                          (depthWriteEnable is ignored), and color writes
101 ///                          will not be affected by the depth test.
102 /// \param depthWriteEnable  enables writing to the depth buffer
103 ///                          if the depth test passes.
104 /// \param depthFunc         function that compares the depth at each sample
105 ///                          in the fragment to the destination depth at the
106 ///                          corresponding sample point.
107 ///
108 /// \donotcall \gx2_typical \enddonotcall
109 ///
110 /// \writesgpu
111 /// \alwayswritesgpu
112 ///
113 void GX2API GX2SetDepthOnlyControl(GX2Boolean depthEnable,
114                                    GX2Boolean depthWriteEnable,
115                                    GX2CompareFunction depthFunc);
116 
117 
118 /// @}
119 /// @addtogroup GX2RenderStatePrimitiveAssemblyGroup
120 /// @{
121 
122 /// \brief Sets culling, front/back polygon modes, polygon offset enables.
123 ///
124 /// \param frontFaceMode         front facing mode
125 /// \param cullFront             enables for front-face culling.
126 /// \param cullBack              enables for back-face culling.
127 /// \param enablePolygonModes    enables polygon mode.
128 /// \param polygonModeFront      mode to render front-facing polygons
129 /// \param polygonModeBack       mode to render back-facing polygons.
130 /// \param polyOffsetFrontEnable enables front facing polygon offset.
131 /// \param polyOffsetBackEnable  enables back facing polygon offset.
132 /// \param pointLineOffsetEnable enables polygon offset for non-triangle
133 ///                              primitives.
134 /// \donotcall \gx2_typical \enddonotcall
135 ///
136 /// \writesgpu
137 /// \alwayswritesgpu
138 ///
139 void GX2API GX2SetPolygonControl(GX2FrontFaceMode frontFaceMode,
140                                    GX2Boolean cullFront,
141                                    GX2Boolean cullBack,
142 
143                                    GX2Boolean     enablePolygonModes,
144                                    GX2PolygonMode polygonModeFront,
145                                    GX2PolygonMode polygonModeBack,
146 
147                                    GX2Boolean polyOffsetFrontEnable,
148                                    GX2Boolean polyOffsetBackEnable,
149                                    GX2Boolean pointLineOffsetEnable);
150 
151 /// \brief An alternate API to set culling and disable offsets & front/back mode.
152 ///
153 /// \note *Disables offsets*, *disables front/back mode*, sets culling as specified.
154 ///
155 /// \param frontFaceMode         front facing mode
156 /// \param cullFront             enables for front-face culling.
157 /// \param cullBack              enables for back-face culling.
158 ///
159 /// \donotcall \gx2_typical \enddonotcall
160 ///
161 /// \writesgpu
162 /// \alwayswritesgpu
163 ///
164 void GX2API GX2SetCullOnlyControl(GX2FrontFaceMode frontFaceMode,
165                                   GX2Boolean cullFront,
166                                   GX2Boolean cullBack);
167 
168 /// @}
169 /// @addtogroup GX2RenderStateDepthStencilGroup
170 /// @{
171 
172 /// \brief Set stencil mask, write mask, and reference values.
173 ///
174 /// \param preMaskFront    mask used with the reference and current stencil values
175 ///                        prior to doing the stencil test for front-facing pixels
176 /// \param writeMaskFront  mask used when writing to the stencil buffer for
177 ///                        front-facing pixels
178 /// \param refFront        reference stencil value for front-facing pixels
179 /// \param preMaskBack     the mask used with the reference and current stencil values
180 ///                        prior to doing the stencil test for back-facing pixels
181 /// \param writeMaskBack   mask used when writing to the stencil buffer for
182 ///                        back-facing pixels
183 /// \param refBack         reference stencil value for back-facing pixels
184 ///
185 /// \donotcall \gx2_typical \enddonotcall
186 ///
187 /// \writesgpu
188 /// \alwayswritesgpu
189 ///
190 void GX2API GX2SetStencilMask(u8 preMaskFront,
191                               u8 writeMaskFront,
192                               u8 refFront,
193                               u8 preMaskBack,
194                               u8 writeMaskBack,
195                               u8 refBack);
196 
197 /// @}
198 /// @addtogroup GX2RenderStateRenderTargetGroup
199 /// @{
200 
201 /// \brief Set the hardware state to perform special accelerated operations.
202 ///
203 /// \param state Select special hardware state to enable/disable
204 /// \param enable Enable/disable special hardware state
205 ///
206 /// \note Disabling \p GX2_SPECIAL_STATE_EXPAND_COLOR or
207 /// \p GX2_SPECIAL_STATE_RESOLVE_COLOR also sets
208 /// \ref GX2SetColorControl to the GX2 default state.
209 ///
210 /// \note Disabling \p GX2_SPECIAL_STATE_CLEAR also sets
211 /// \ref GX2SetRasterizerClipControl to the GX2 default state.
212 ///
213 /// \warning Special states must be disabled to return the hardware
214 ///          to a normal rendering state.
215 ///
216 /// \warning Only a single special hardware state may be enabled at a time
217 ///          unless otherwise noted. The enabled state must be disabled
218 ///          in order to return to normal rendering operations.
219 ///
220 /// \clobberstate
221 ///
222 /// \donotcall \gx2_typical \enddonotcall
223 ///
224 /// \writesgpu
225 /// \alwayswritesgpu
226 ///
227 void GX2API GX2SetSpecialState(GX2SpecialState state,
228                                GX2Boolean enable);
229 
230 /// \brief Set alpha test controls.
231 ///
232 /// \param alphaTestEnable Enable if GX2_ENABLE, Disable if GX2_DISABLE
233 /// \param alphaFunc Compare Function for alpha testing
234 /// \param ref Reference value for alpha testing
235 ///
236 /// \donotcall \gx2_typical \enddonotcall
237 ///
238 /// \writesgpu
239 /// \alwayswritesgpu
240 ///
241 void GX2API GX2SetAlphaTest(GX2Boolean alphaTestEnable,
242                             GX2CompareFunction alphaFunc,
243                             f32 ref);
244 
245 /// \brief Set the alpha to mask controls (used for screen-door transparency).
246 ///
247 /// \param alphaToMaskEnable if enabled, the sample mask is ANDed with a mask
248 ///                          produced from the alpha value.
249 /// \param mode Mode for the alpha mask.
250 ///
251 /// \donotcall \gx2_typical \enddonotcall
252 ///
253 /// \writesgpu
254 /// \alwayswritesgpu
255 ///
256 void GX2API GX2SetAlphaToMask(GX2Boolean alphaToMaskEnable,
257                               GX2AlphaToMaskMode mode);
258 
259 /// @}
260 /// @addtogroup GX2RenderStatePrimitiveAssemblyGroup
261 /// @{
262 
263 /// \brief Set polygon offset values (z-bias).
264 ///
265 /// Please refer to \ref GX2PolygonOffsetInfo for more information.
266 ///
267 /// \param frontOffset  offset value for front-facing polygons
268 /// \param frontSlopeScale  slope scale value for front-facing polygons
269 /// \param backOffset   offset value for back-facing polygons
270 /// \param backSlopeScale   slope scale value for back-facing polygons
271 /// \param clamp        maximum (if positive) or minimum
272 ///                         (if negative) value for the final offset, ignored if 0.
273 ///
274 /// \donotcall \gx2_typical \enddonotcall
275 ///
276 /// \writesgpu
277 /// \alwayswritesgpu
278 ///
279 void GX2API GX2SetPolygonOffset(f32 frontOffset, f32 frontSlopeScale,
280                                 f32 backOffset,  f32 backSlopeScale,  f32 clamp);
281 
282 /// @}
283 /// @addtogroup GX2RenderStateRenderTargetGroup
284 /// @{
285 
286 /// \brief Defines the color channels that will be written to for each render target.
287 ///
288 /// \note The set of enabled targets is controlled by both the number of
289 ///       shader outputs as well as these values (and by multiwriteEnable,
290 ///       \ref GX2SetColorControl).
291 ///       It's probably a good idea to disable unused targets here.
292 ///
293 /// \note Using MRTs is not compatible with dual-source blending
294 ///       (see \ref GX2SetBlendControl).  For dual-source blending,
295 ///       only target0 needs to be enabled.
296 ///
297 /// \param target0 positive mask for writing to MRT 0 components.
298 /// \param target1 positive mask for writing to MRT 1 components.
299 /// \param target2 positive mask for writing to MRT 2 components.
300 /// \param target3 positive mask for writing to MRT 3 components.
301 /// \param target4 positive mask for writing to MRT 4 components.
302 /// \param target5 positive mask for writing to MRT 5 components.
303 /// \param target6 positive mask for writing to MRT 6 components.
304 /// \param target7 positive mask for writing to MRT 7 components.
305 ///
306 /// \donotcall \gx2_typical \enddonotcall
307 ///
308 /// \writesgpu
309 /// \alwayswritesgpu
310 ///
311 void GX2API GX2SetTargetChannelMasks(GX2ChannelMask target0,
312                                      GX2ChannelMask target1,
313                                      GX2ChannelMask target2,
314                                      GX2ChannelMask target3,
315                                      GX2ChannelMask target4,
316                                      GX2ChannelMask target5,
317                                      GX2ChannelMask target6,
318                                      GX2ChannelMask target7);
319 
320 /// \brief Sets the quad-pipe (2x2) masks to be used for Multisample AA.
321 ///
322 /// \param upperLeftMask contains an 8-bit mask, LSB is Sample0, MSB is Sample7
323 /// \param upperRightMask contains an 8-bit mask, LSB is Sample0, MSB is Sample7
324 /// \param lowerLeftMask contains an 8-bit mask, LSB is Sample0, MSB is Sample7
325 /// \param lowerRightMask contains an 8-bit mask, LSB is Sample0, MSB is Sample7
326 ///
327 /// This affects how MSAA buffers are written by the quad-pipe. Each
328 /// 2x2 region of screen aligned pixels has a separate 8-bit mask.
329 ///
330 /// Setting the mask disables writing to the given sample in the output
331 /// MSAA buffer. This can be used for performance reasons. The default
332 /// mask is 0xFF (enabled) for all quadrants.
333 ///
334 /// \donotcall \gx2_typical \enddonotcall
335 ///
336 /// \writesgpu
337 /// \alwayswritesgpu
338 ///
339 void GX2API GX2SetAAMask(u8 upperLeftMask,
340                          u8 upperRightMask,
341                          u8 lowerLeftMask,
342                          u8 lowerRightMask);
343 
344 /// \brief Set logic ops, blend enables, color enable, and multi-write enable.
345 ///
346 /// \note Enabling multiwriteEnable is not compatible with dual-source blending
347 ///       (see \ref GX2SetBlendControl).
348 ///
349 /// \param lop  a logical operation that describes how source & dest are combined.
350 ///      Logic op is mutually exclusive with blending.  The lop must be GX2_LOGIC_OP_COPY
351 ///      if ANY blending is enabled (if blendEnableMask is not 0).
352 /// \param blendEnableMask   an 8-bit mask that enables blending per render target.
353 /// \param multiwriteEnable  if true, the output of MRT 0 is sent to all MRTs.
354 /// \param colorBufferEnable enables drawing to the color buffer.
355 ///      The colorBufferEnable should be set to GX2_DISABLE for optimal performance when doing
356 ///      Z only rendering.
357 ///
358 /// \donotcall \gx2_typical \enddonotcall
359 ///
360 /// \writesgpu
361 /// \alwayswritesgpu
362 ///
363 void GX2API GX2SetColorControl(GX2LogicOp  lop,
364                                u8          blendEnableMask,
365                                GX2Boolean  multiwriteEnable,
366                                GX2Boolean  colorBufferEnable);
367 
368 /// \brief Set color and alpha blending controls (src, dst, etc.).
369 ///
370 /// \note Using a blend function that includes source 1 implies dual-source blending.
371 ///       This is mutually exclusive with MRTs.  It is also not compatible
372 ///       with multiwriteEnable (\ref GX2SetColorControl).
373 ///       It requires a pixel shader with 2 color output channels
374 ///       (gl_FragData[0] and gl_FragData[1]).
375 ///
376 /// \param target         render target to set blend controls for
377 /// \param colorSrcBlend  source blend function for color components
378 /// \param colorDstBlend  destination blend function for color components
379 /// \param colorCombine   source/dest combination function for color components
380 /// \param separateAlphaBlend  if true, use the following fields for alpha blend.
381 ///                            if false, use the color fields for alpha blend.
382 /// \param alphaSrcBlend  source blend function for alpha
383 /// \param alphaDstBlend  destination blend function for alpha
384 /// \param alphaCombine   source/dest combination function for alpha
385 ///
386 /// \donotcall \gx2_typical \enddonotcall
387 ///
388 /// \writesgpu
389 /// \alwayswritesgpu
390 ///
391 void GX2API GX2SetBlendControl(GX2RenderTarget target,
392                                GX2BlendFunction colorSrcBlend,
393                                GX2BlendFunction colorDstBlend,
394                                GX2BlendCombine  colorCombine,
395                                GX2Boolean       separateAlphaBlend,
396                                GX2BlendFunction alphaSrcBlend,
397                                GX2BlendFunction alphaDstBlend,
398                                GX2BlendCombine  alphaCombine);
399 
400 /// \brief Set the components of the constant blend color.
401 ///
402 /// \param red   red
403 /// \param green green
404 /// \param blue  blue
405 /// \param alpha alpha
406 ///
407 /// \donotcall \gx2_typical \enddonotcall
408 ///
409 /// \writesgpu
410 /// \alwayswritesgpu
411 ///
412 void GX2API GX2SetBlendConstantColor(f32 red, f32 green, f32 blue, f32 alpha);
413 
414 /// @}
415 /// @addtogroup GX2RenderStatePrimitiveAssemblyGroup
416 /// @{
417 
418 /// \brief Set the "diameter" of rasterized points (when not specified by a shader).
419 ///
420 /// Width and height are specified in pixels, with a precision of 1/8 pixel.
421 ///
422 /// \param width Width of points
423 /// \param height Height of points
424 ///
425 /// \donotcall \gx2_typical \enddonotcall
426 ///
427 /// \writesgpu
428 /// \alwayswritesgpu
429 ///
430 void GX2API GX2SetPointSize(f32 width, f32 height);
431 
432 /// \brief Set the minimum & maximum point sizes
433 /// (when specified by a shader, for instance).
434 ///
435 /// Width and height are specified in pixels, with a precision of 1/8 pixel.
436 ///
437 /// \note the per-vertex point size or the value set by \ref GX2SetPointSize
438 /// is clamped to the limits provided by this API.
439 ///
440 /// \param min limit min size of points
441 /// \param max limit max size of points
442 ///
443 /// \donotcall \gx2_typical \enddonotcall
444 ///
445 /// \writesgpu
446 /// \alwayswritesgpu
447 ///
448 void GX2API GX2SetPointLimits(f32 min, f32 max);
449 
450 /// \brief Set the width of rasterized lines.
451 ///
452 /// Width is specified in pixels, with a precision of 1/8 pixel.
453 ///
454 /// \param width Width of lines
455 ///
456 /// \donotcall \gx2_typical \enddonotcall
457 ///
458 /// \writesgpu
459 /// \alwayswritesgpu
460 ///
461 void GX2API GX2SetLineWidth(f32 width);
462 
463 /// \brief Set viewport and depth range.
464 ///
465 /// \param xOrig orig x point of viewport
466 /// \param yOrig orig y point of viewport
467 /// \param wd width of viewport
468 /// \param ht height of viewport
469 /// \param nearZ near range of depth (typically 0.0)
470 /// \param farZ far range of depth (typically 1.0)
471 ///
472 /// \donotcall \gx2_typical \enddonotcall
473 ///
474 /// \writesgpu
475 /// \alwayswritesgpu
476 ///
477 void GX2API GX2SetViewport(f32 xOrig, f32 yOrig, f32 wd, f32 ht, f32 nearZ, f32 farZ);
478 
479 
480 /// \brief Version of GX2SetViewport to call when Z output range is 0 < z < 1.
481 ///
482 /// \param xOrig orig x point of viewport
483 /// \param yOrig orig y point of viewport
484 /// \param wd width of viewport
485 /// \param ht height of viewport
486 /// \param nearZ near range of depth (typically 0.0)
487 /// \param farZ far range of depth (typically 1.0)
488 ///
489 /// \donotcall \gx2_typical \enddonotcall
490 ///
491 /// \writesgpu
492 /// \alwayswritesgpu
493 ///
GX2SetViewportHalfZ(f32 xOrig,f32 yOrig,f32 wd,f32 ht,f32 nearZ,f32 farZ)494 GX2_INLINE void GX2SetViewportHalfZ(f32 xOrig, f32 yOrig, f32 wd, f32 ht, f32
495 nearZ, f32 farZ) {
496     GX2SetViewport(xOrig, yOrig, wd, ht, (2*nearZ-farZ), farZ);
497 }
498 
499 
500 /// \brief Set scissor box.
501 ///
502 /// \param xOrig orig x point of scissor box
503 /// \param yOrig orig y point of scissor box
504 /// \param wd width of scissor box
505 /// \param ht height of scissor box
506 ///
507 /// \donotcall \gx2_typical \enddonotcall
508 ///
509 /// \writesgpu
510 /// \alwayswritesgpu
511 ///
512 void GX2API GX2SetScissor(u32 xOrig, u32 yOrig, u32 wd, u32 ht);
513 
514 /// @}
515 /// @addtogroup GX2RenderStatePrimitiveAssemblyGroup
516 /// @{
517 
518 /// \brief Enables the rasterizer and clipping
519 ///
520 /// \note If the rasterizer is disabled all operations after the geometry shader (or vertex shader
521 ///       if the geometry shader is not used) are disabled.  This includes viewport transform and
522 ///       clipping.
523 ///
524 /// \param rasterizerEnable  Enable for the rasterizer
525 /// \param zClipEnable       Enable ZNear and ZFar clipping
526 ///
527 /// \donotcall \gx2_typical \enddonotcall
528 ///
529 /// \writesgpu
530 /// \alwayswritesgpu
531 ///
532 void GX2API GX2SetRasterizerClipControl(GX2Boolean rasterizerEnable, GX2Boolean zClipEnable);
533 
534 /// \brief Enables the rasterizer and clipping options
535 ///
536 /// \note If the rasterizer is disabled all operations after the geometry shader (or vertex shader
537 ///       if the geometry shader is not used) are disabled.  This includes viewport transform and
538 ///       clipping.
539 ///
540 /// \param rasterizerEnable         Enable for the rasterizer
541 /// \param zClipEnable              Enable ZNear and ZFar clipping
542 /// \param enableHalfSizeClipSpace  Set normalized device coordinates to [0,1] for Z
543 ///
544 /// \donotcall \gx2_typical \enddonotcall
545 ///
546 /// \writesgpu
547 /// \alwayswritesgpu
548 ///
549 void GX2API GX2SetRasterizerClipControlEx(GX2Boolean rasterizerEnable, GX2Boolean zClipEnable, GX2Boolean enableHalfSizeClipSpace);
550 
551 /// \brief Deprecated synonym for \ref GX2SetRasterizerClipControlEx
552 ///
553 /// \deprecated This API name is deprecated.  Please use \ref
554 ///             GX2SetRasterizerClipControlEx instead.
555 ///
556 /// \donotcall \gx2_typical \enddonotcall
557 ///
558 /// \writesgpu
559 /// \alwayswritesgpu
560 ///
561 ///
562 void GX2API GX2SetRasterizerClipControlHalfZ(GX2Boolean rasterizerEnable, GX2Boolean zClipEnable, GX2Boolean enableHalfSizeClipSpace);
563 
564 /// @}
565 /// @}
566 
567 #ifdef __cplusplus
568 }
569 #endif // __cplusplus
570 
571 #endif // _CAFE_GX2_RENDERSTATE_H_
572