2 * Mesa 3-D graphics library
5 * Copyright (C) 1999-2003 Brian Paul All Rights Reserved.
7 * Permission is hereby granted, free of charge, to any person obtaining a
8 * copy of this software and associated documentation files (the "Software"),
9 * to deal in the Software without restriction, including without limitation
10 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
11 * and/or sell copies of the Software, and to permit persons to whom the
12 * Software is furnished to do so, subject to the following conditions:
14 * The above copyright notice and this permission notice shall be included
15 * in all copies or substantial portions of the Software.
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
18 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
20 * BRIAN PAUL BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
21 * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
22 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
27 * \brief TnL module datatypes and definitions.
28 * \author Keith Whitwell
33 * \mainpage The TNL-module
35 * TNL stands for "transform and lighting", i.e. this module implements
36 * a pipeline that receives as input a buffer of vertices and does all
37 * necessary transformations (rotations, clipping, vertex shader etc.)
38 * and passes then the output to the rasterizer.
40 * The gl_pipeline contains the array of all stages, which should be
41 * applied. Each stage is a black-box, which is described by an
42 * gl_pipeline_stage. The function ::_tnl_run_pipeline applies all the
43 * stages to the vertex_buffer TNLcontext::vb, where the vertex data
44 * is stored. The last stage in the pipeline is the rasterizer.
46 * The initial vertex_buffer data may either come from an ::immediate
47 * structure or client vertex_arrays or display lists:
50 * - The ::immediate structure records all the GL commands issued between
51 * glBegin and glEnd. \n
52 * The structure accumulates data, until it is either full or it is
53 * flushed (usually by a state change). Before starting then the pipeline,
54 * the collected vertex data in ::immediate has to be pushed into
56 * This happens in ::_tnl_vb_bind_immediate. The pipeline is then run by
57 * calling tnl_device_driver::RunPipeline = ::_tnl_run_pipeline, which
58 * is stored in TNLcontext::Driver. \n
59 * An ::immediate does (for performance reasons) usually not finish with a
60 * glEnd, and hence it also does not need to start with a glBegin.
61 * This means that the last vertices of one ::immediate may need to be
62 * saved for the next one.
65 * - NOT SURE ABOUT THIS: The vertex_arrays structure is used to handle
66 * glDrawArrays etc. \n
67 * Here, the data of the vertex_arrays is copied by ::_tnl_vb_bind_arrays
68 * into TNLcontext::vb, so that the pipeline can be started.
79 #include "math/m_matrix.h"
80 #include "math/m_vector.h"
81 #include "math/m_xform.h"
84 #define MAX_PIPELINE_STAGES 30
87 /* Numbers for sizing immediate structs.
89 #define IMM_MAX_COPIED_VERTS 3
90 #define IMM_MAXDATA (216 + IMM_MAX_COPIED_VERTS)
91 #define IMM_SIZE (IMM_MAXDATA + MAX_CLIPPED_VERTICES)
94 /* Values for IM->BeginState
96 #define VERT_BEGIN_0 0x1 /* glBegin (if initially inside beg/end) */
97 #define VERT_BEGIN_1 0x2 /* glBegin (if initially outside beg/end) */
98 #define VERT_ERROR_0 0x4 /* invalid_operation in initial state 0 */
99 #define VERT_ERROR_1 0x8 /* invalid_operation in initial state 1 */
102 /* Flags to be added to the primitive enum in VB->Primitive.
104 #define PRIM_MODE_MASK 0xff /* Extract the actual primitive */
105 #define PRIM_BEGIN 0x100 /* The prim starts here (not wrapped) */
106 #define PRIM_END 0x200 /* The prim ends in this VB (does not wrap) */
107 #define PRIM_PARITY 0x400 /* The prim wrapped on an odd number of verts */
108 #define PRIM_LAST 0x800 /* No more prims in the VB */
112 * Flags that describe the inputs and outputs of pipeline stages, and
113 * the contents of a vertex-cassette. We reuse the VERT_BIT_* flags
114 * defined in mtypes.h and add a bunch of new ones.
116 /* bits 0..5 defined in mtypes.h */
117 #define VERT_BIT_INDEX VERT_BIT_SIX /* a free vertex attrib bit */
118 #define VERT_BIT_EDGEFLAG VERT_BIT_SEVEN /* a free vertex attrib bit */
119 /* bits 8..15 defined in mtypes.h */
120 #define VERT_BIT_EVAL_C1 (1 << 16) /* imm only */
121 #define VERT_BIT_EVAL_C2 (1 << 17) /* imm only */
122 #define VERT_BIT_EVAL_P1 (1 << 18) /* imm only */
123 #define VERT_BIT_EVAL_P2 (1 << 19) /* imm only */
124 #define VERT_BIT_OBJ_3 (1 << 20) /* imm only */
125 #define VERT_BIT_OBJ_4 (1 << 21) /* imm only */
126 #define VERT_BIT_MATERIAL (1 << 22) /* imm only, but tested in vb code */
127 #define VERT_BIT_ELT (1 << 23) /* imm only */
128 #define VERT_BIT_BEGIN (1 << 24) /* imm only, but tested in vb code */
129 #define VERT_BIT_END (1 << 25) /* imm only, but tested in vb code */
130 #define VERT_BIT_END_VB (1 << 26) /* imm only, but tested in vb code */
131 #define VERT_BIT_POINT_SIZE (1 << 27) /* vb only, could reuse a bit */
132 #define VERT_BIT_EYE VERT_BIT_BEGIN /* vb only, reuse imm bit */
133 #define VERT_BIT_CLIP VERT_BIT_END /* vb only, reuse imm bit*/
136 /* Flags for IM->TexCoordSize. Enough flags for 16 units.
138 #define TEX_0_SIZE_3 (unsigned)0x1
139 #define TEX_0_SIZE_4 (unsigned)0x10001
140 #define TEX_SIZE_3(unit) (TEX_0_SIZE_3 << (unit))
141 #define TEX_SIZE_4(unit) (TEX_0_SIZE_4 << (unit))
146 #define VERT_BITS_OBJ_23 (VERT_BIT_POS | VERT_BIT_OBJ_3)
147 #define VERT_BITS_OBJ_234 (VERT_BIT_POS | VERT_BIT_OBJ_3 | VERT_BIT_OBJ_4)
149 #define VERT_BITS_TEX_ANY (VERT_BIT_TEX0 | \
158 #define VERT_BITS_EVAL_ANY (VERT_BIT_EVAL_C1 | VERT_BIT_EVAL_P1 | \
159 VERT_BIT_EVAL_C2 | VERT_BIT_EVAL_P2)
161 #define VERT_BITS_FIXUP (VERT_BITS_TEX_ANY | \
166 VERT_BIT_EDGEFLAG | \
169 #define VERT_BITS_CURRENT_DATA (VERT_BITS_FIXUP | \
172 #define VERT_BITS_DATA (VERT_BITS_TEX_ANY | \
177 VERT_BIT_EDGEFLAG | \
180 VERT_BIT_MATERIAL | \
187 * Stores everything that can take place between a glBegin and glEnd.
188 * Adjacent glBegin/glEnd pairs are stored back-to-back when there's no
189 * state changes between them.
190 * Used for immediate mode rendering and display lists.
194 GLuint id
, ref_count
;
196 /* This must be saved when immediates are shared in display lists.
198 GLuint CopyStart
, Start
, Count
;
199 GLuint LastData
; /* count or count+1 */
200 GLuint AndFlag
, OrFlag
;
201 GLuint TexSize
; /* keep track of texcoord sizes */
202 GLuint BeginState
, SavedBeginState
;
203 GLuint LastPrimitive
;
205 GLuint ArrayEltFlags
; /* precalc'ed for glArrayElt */
207 GLuint ArrayEltFlush
;
209 #define FLUSH_ELT_EAGER 0x1
210 #define FLUSH_ELT_LAZY 0x2
213 GLuint MaxTextureUnits
; /* precalc'ed for glMultiTexCoordARB */
215 /* Temporary values created when vertices are copied into the
216 * first 3 slots of the struct:
224 /* allocate storage for these on demand:
226 struct gl_material
*Material
;
227 GLuint
*MaterialMask
;
229 GLuint MaterialOrMask
;
230 GLuint MaterialAndMask
;
232 GLuint Primitive
[IMM_SIZE
]; /* BEGIN/END */
233 GLuint PrimitiveLength
[IMM_SIZE
]; /* BEGIN/END */
234 GLuint Flag
[IMM_SIZE
]; /* VERT_BIT_* flags */
236 /* Attrib is an array [MAX_VERT_ATTRIBS] of pointer to array [][4]
238 * We only pre-allocate the vertex position array. The other vertex
239 * attribute arrays are only allocated when needed to save memory.
241 GLfloat (*Attrib
[VERT_ATTRIB_MAX
])[4];
243 GLfloat
*NormalLengthPtr
; /* length of normal vectors (display list only) */
245 GLuint Elt
[IMM_SIZE
];
246 GLubyte EdgeFlag
[IMM_SIZE
];
247 GLuint Index
[IMM_SIZE
];
253 /* Conventional vertex attribute arrays */
256 struct gl_client_array Color
;
257 struct gl_client_array SecondaryColor
;
259 GLvector4f TexCoord
[MAX_TEXTURE_COORD_UNITS
];
260 GLvector1ub EdgeFlag
;
264 /* These attributes don't alias with the conventional attributes.
265 * The GL_NV_vertex_program extension defines 16 extra sets of vertex
266 * arrays which have precedent over the conventional arrays when enabled.
268 GLvector4f Attribs
[VERT_ATTRIB_MAX
];
273 * Contains the current state of a running pipeline.
275 typedef struct vertex_buffer
277 /* Constant over life of the vertex_buffer.
281 /* Constant over the pipeline.
283 GLuint Count
; /* for everything except Elts */
284 GLuint FirstClipped
; /* temp verts for clipping */
285 GLuint FirstPrimitive
; /* usually zero */
287 /* Pointers to current data.
289 GLuint
*Elts
; /* VERT_BIT_ELT */
290 GLvector4f
*ObjPtr
; /* VERT_BIT_POS */
291 GLvector4f
*EyePtr
; /* VERT_BIT_EYE */
292 GLvector4f
*ClipPtr
; /* VERT_BIT_CLIP */
293 GLvector4f
*NdcPtr
; /* VERT_BIT_CLIP (2) */
294 GLubyte ClipOrMask
; /* VERT_BIT_CLIP (3) */
295 GLubyte
*ClipMask
; /* VERT_BIT_CLIP (4) */
296 GLvector4f
*NormalPtr
; /* VERT_BIT_NORMAL */
297 GLfloat
*NormalLengthPtr
; /* VERT_BIT_NORMAL */
298 GLboolean
*EdgeFlag
; /* VERT_BIT_EDGEFLAG */
299 GLvector4f
*TexCoordPtr
[MAX_TEXTURE_COORD_UNITS
]; /* VERT_TEX_0..n */
300 GLvector1ui
*IndexPtr
[2]; /* VERT_BIT_INDEX */
301 struct gl_client_array
*ColorPtr
[2]; /* VERT_BIT_COLOR0 */
302 struct gl_client_array
*SecondaryColorPtr
[2];/* VERT_BIT_COLOR1 */
303 GLvector4f
*PointSizePtr
; /* VERT_BIT_POINT_SIZE */
304 GLvector4f
*FogCoordPtr
; /* VERT_BIT_FOG */
305 struct gl_material
*Material
; /* VERT_BIT_MATERIAL, optional */
306 GLuint
*MaterialMask
; /* VERT_BIT_MATERIAL, optional */
307 GLuint
*Flag
; /* VERT_BIT_* flags, optional */
308 GLuint
*Primitive
; /* GL_(mode)|PRIM_* flags */
309 GLuint
*PrimitiveLength
; /* integers */
311 /* Inputs to the vertex program stage */
312 GLvector4f
*AttribPtr
[VERT_ATTRIB_MAX
]; /* GL_NV_vertex_program */
314 GLuint importable_data
;
316 void (*import_data
)( GLcontext
*ctx
, GLuint flags
, GLuint vecflags
);
317 /* Callback to the provider of the untransformed input for the
318 * render stage (or other stages) to call if they need to write into
319 * write-protected arrays, or fixup the stride on input arrays.
321 * This is currently only necessary for client arrays that make it
322 * as far down the pipeline as the render stage.
326 /* Private data from _tnl_render_stage that has no business being
334 /** Describes an individual operation on the pipeline.
336 struct gl_pipeline_stage
{
338 GLuint check_state
; /* All state referenced in check() --
339 * When is the pipeline_stage struct
340 * itself invalidated? Must be
344 /* Usually constant or set by the 'check' callback:
346 GLuint run_state
; /* All state referenced in run() --
347 * When is the cached output of the
351 GLboolean active
; /* True if runnable in current state */
352 GLuint inputs
; /* VERT_* inputs to the stage */
353 GLuint outputs
; /* VERT_* outputs of the stage */
355 /* Set in _tnl_run_pipeline():
357 GLuint changed_inputs
; /* Generated value -- inputs to the
358 * stage that have changed since last
362 /* Private data for the pipeline stage:
366 /* Free private data. May not be null.
368 void (*destroy
)( struct gl_pipeline_stage
* );
370 /* Called from _tnl_validate_pipeline(). Must update all fields in
371 * the pipeline_stage struct for the current state.
373 void (*check
)( GLcontext
*ctx
, struct gl_pipeline_stage
* );
375 /* Called from _tnl_run_pipeline(). The stage.changed_inputs value
376 * encodes all inputs to thee struct which have changed. If
377 * non-zero, recompute all affected outputs of the stage, otherwise
378 * execute any 'sideeffects' of the stage.
380 * Return value: GL_TRUE - keep going
381 * GL_FALSE - finished pipeline
383 GLboolean (*run
)( GLcontext
*ctx
, struct gl_pipeline_stage
* );
386 /** Contains the array of all pipeline stages.
387 * The default values are defined at the end of t_pipeline.c */
389 GLuint build_state_trigger
; /**< state changes which require build */
390 GLuint build_state_changes
; /**< state changes since last build */
391 GLuint run_state_changes
; /**< state changes since last run */
392 GLuint run_input_changes
; /**< VERT_* changes since last run */
393 GLuint inputs
; /**< VERT_* inputs to pipeline */
394 /** This array has to end with a NULL-pointer. */
395 struct gl_pipeline_stage stages
[MAX_PIPELINE_STAGES
+1];
400 struct tnl_eval_store
{
401 GLuint EvalMap1Flags
;
402 GLuint EvalMap2Flags
;
403 GLuint EvalMap1AttribFlags
; /* GL_NV_vertex_program */
404 GLuint EvalMap2AttribFlags
; /* GL_NV_vertex_program */
406 struct immediate
*im
; /* used for temporary data */
410 typedef void (*points_func
)( GLcontext
*ctx
, GLuint first
, GLuint last
);
411 typedef void (*line_func
)( GLcontext
*ctx
, GLuint v1
, GLuint v2
);
412 typedef void (*triangle_func
)( GLcontext
*ctx
,
413 GLuint v1
, GLuint v2
, GLuint v3
);
414 typedef void (*quad_func
)( GLcontext
*ctx
, GLuint v1
, GLuint v2
,
415 GLuint v3
, GLuint v4
);
416 typedef void (*render_func
)( GLcontext
*ctx
, GLuint start
, GLuint count
,
418 typedef void (*interp_func
)( GLcontext
*ctx
,
419 GLfloat t
, GLuint dst
, GLuint out
, GLuint in
,
420 GLboolean force_boundary
);
421 typedef void (*copy_pv_func
)( GLcontext
*ctx
, GLuint dst
, GLuint src
);
422 typedef void (*setup_func
)( GLcontext
*ctx
,
423 GLuint start
, GLuint end
,
427 struct tnl_device_driver
{
432 void (*RunPipeline
)(GLcontext
*ctx
);
433 /* Replaces PipelineStart/PipelineFinish -- intended to allow
434 * drivers to wrap _tnl_run_pipeline() with code to validate state
435 * and grab/release hardware locks.
438 void (*NotifyMaterialChange
)(GLcontext
*ctx
);
439 /* Alert tnl-aware drivers of changes to material.
442 GLboolean (*NotifyBegin
)(GLcontext
*ctx
, GLenum p
);
443 /* Allow drivers to hook in optimized begin/end engines.
444 * Return value: GL_TRUE - driver handled the begin
445 * GL_FALSE - driver didn't handle the begin
449 *** Rendering -- These functions called only from t_vb_render.c
452 void (*Start
)(GLcontext
*ctx
);
453 void (*Finish
)(GLcontext
*ctx
);
454 /* Called before and after all rendering operations, including DrawPixels,
455 * ReadPixels, Bitmap, span functions, and CopyTexImage, etc commands.
456 * These are a suitable place for grabbing/releasing hardware locks.
459 void (*PrimitiveNotify
)(GLcontext
*ctx
, GLenum mode
);
460 /* Called between RenderStart() and RenderFinish() to indicate the
461 * type of primitive we're about to draw. Mode will be one of the
462 * modes accepted by glBegin().
466 /* The interp function is called by the clipping routines when we need
467 * to generate an interpolated vertex. All pertinant vertex ancilliary
468 * data should be computed by interpolating between the 'in' and 'out'
473 /* The copy function is used to make a copy of a vertex. All pertinant
474 * vertex attributes should be copied.
477 void (*ClippedPolygon
)( GLcontext
*ctx
, const GLuint
*elts
, GLuint n
);
478 /* Render a polygon with <n> vertices whose indexes are in the <elts>
482 void (*ClippedLine
)( GLcontext
*ctx
, GLuint v0
, GLuint v1
);
483 /* Render a line between the two vertices given by indexes v0 and v1. */
485 points_func Points
; /* must now respect vb->elts */
487 triangle_func Triangle
;
489 /* These functions are called in order to render points, lines,
490 * triangles and quads. These are only called via the T&L module.
493 render_func
*PrimTabVerts
;
494 render_func
*PrimTabElts
;
495 /* Render whole unclipped primitives (points, lines, linestrips,
496 * lineloops, etc). The tables are indexed by the GL enum of the
497 * primitive to be rendered. RenderTabVerts is used for non-indexed
498 * arrays of vertices. RenderTabElts is used for indexed arrays of
502 void (*ResetLineStipple
)( GLcontext
*ctx
);
503 /* Reset the hardware's line stipple counter.
506 setup_func BuildVertices
;
507 /* This function is called whenever new vertices are required for
508 * rendering. The vertices in question are those n such that start
509 * <= n < end. The new_inputs parameter indicates those fields of
510 * the vertex which need to be updated, if only a partial repair of
511 * the vertex is required.
513 * This function is called only from _tnl_render_stage in tnl/t_render.c.
517 GLboolean (*Multipass
)( GLcontext
*ctx
, GLuint passno
);
518 /* Driver may request additional render passes by returning GL_TRUE
519 * when this function is called. This function will be called
520 * after the first pass, and passes will be made until the function
521 * returns GL_FALSE. If no function is registered, only one pass
524 * This function will be first invoked with passno == 1.
534 struct tnl_device_driver Driver
;
536 /* Track whether the module is active.
538 GLboolean bound_exec
;
540 /* Display list extensions
542 GLuint opcode_vertex_cassette
;
546 struct gl_pipeline pipeline
;
547 struct vertex_buffer vb
;
549 /* GLvectors for binding to vb:
551 struct vertex_arrays imm_inputs
;
552 struct vertex_arrays array_inputs
;
553 GLuint
*tmp_primitive
;
554 GLuint
*tmp_primitive_length
;
556 /* Set when executing an internally generated begin/end object. If
557 * such an object is encountered in a display list, it will be
558 * replayed only if the list is outside any existing begin/end
561 GLboolean ReplayHardBeginEnd
;
563 /* Note which vertices need copying over succesive immediates.
564 * Will add save versions to precompute vertex copying where
567 struct immediate
*ExecCopySource
;
568 GLuint ExecCopyCount
;
569 GLuint ExecCopyElts
[IMM_MAX_COPIED_VERTS
];
570 GLuint ExecCopyTexSize
;
573 GLuint DlistPrimitive
;
574 GLuint DlistPrimitiveLength
;
575 GLuint DlistLastPrimitive
;
577 /* Cache a single free immediate (refcount == 0)
579 struct immediate
*freed_immediate
;
581 /* Probably need a better configuration mechanism:
583 GLboolean NeedNdcCoords
;
584 GLboolean LoopbackDListCassettes
;
585 GLboolean CalcDListNormalLengths
;
586 GLboolean IsolateMaterials
;
588 /* Derived state and storage for _tnl_eval_vb:
590 struct tnl_eval_store eval
;
592 /* Functions to be plugged into dispatch when tnl is active.
594 GLvertexformat vtxfmt
;
595 GLvertexformat save_vtxfmt
;
601 #define TNL_CONTEXT(ctx) ((TNLcontext *)(ctx->swtnl_context))
602 #define TNL_CURRENT_IM(ctx) ((struct immediate *)(ctx->swtnl_im))
605 #define TYPE_IDX(t) ((t) & 0xf)
606 #define MAX_TYPES TYPE_IDX(GL_DOUBLE)+1 /* 0xa + 1 */
608 extern void _tnl_MakeCurrent( GLcontext
*ctx
,
609 GLframebuffer
*drawBuffer
,
610 GLframebuffer
*readBuffer
);
614 * Macros for fetching current input buffer.
617 #define GET_IMMEDIATE struct immediate *IM = TNL_CURRENT_IM(((GLcontext *) (_glapi_Context ? _glapi_Context : _glapi_get_context())))
618 #define SET_IMMEDIATE(ctx, im) ctx->swtnl_im = (void *)im
620 extern struct immediate
*_tnl_CurrentInput
;
621 #define GET_IMMEDIATE struct immediate *IM = _tnl_CurrentInput
622 #define SET_IMMEDIATE(ctx, im) \
624 ctx->swtnl_im = (void *)im; \
625 _tnl_CurrentInput = im; \