1fffc27015b60d4621316ef567a81c5c5dfcb182cKeith WhitwellINTRODUCTION 2fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwell 3fffc27015b60d4621316ef567a81c5c5dfcb182cKeith WhitwellA generic, configurable software implementation of GL transformation & 4fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwelllighting. 5fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwell 6fffc27015b60d4621316ef567a81c5c5dfcb182cKeith WhitwellThis module provides an implementation of the routines required by the 7fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwell'vtxfmt' mechanism of core mesa for tnl functionality in all 8fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwellcombinations of compile and execute modes. 9fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwell 10fffc27015b60d4621316ef567a81c5c5dfcb182cKeith WhitwellMost current drivers use the tnl module exclusively to provide this 115266c87c873057d9d3ecdaf1745d99225a5dc292Ian Romanickfunctionality. 12fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwell 13fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwell 14fffc27015b60d4621316ef567a81c5c5dfcb182cKeith WhitwellSTATE 15fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwell 16fffc27015b60d4621316ef567a81c5c5dfcb182cKeith WhitwellTo create and destroy the module: 17fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwell 18f9995b30756140724f41daf963fa06167912be7fKristian Høgsberg GLboolean _tnl_CreateContext( struct gl_context *ctx ); 19f9995b30756140724f41daf963fa06167912be7fKristian Høgsberg void _tnl_DestroyContext( struct gl_context *ctx ); 20fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwell 21fffc27015b60d4621316ef567a81c5c5dfcb182cKeith WhitwellThe module is not active by default, and must be installed by calling 22fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwell_tnl_Wakeup(). This function installs internal tnl functions into all 23fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwellthe vtxfmt dispatch hooks, thus taking over the task of transformation 24fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwelland lighting entirely: 25fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwell 26f9995b30756140724f41daf963fa06167912be7fKristian Høgsberg void _tnl_wakeup_exec( struct gl_context *ctx ); 27f9995b30756140724f41daf963fa06167912be7fKristian Høgsberg void _tnl_wakeup_save_exec( struct gl_context *ctx ); 28fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwell 29fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwell 30fffc27015b60d4621316ef567a81c5c5dfcb182cKeith WhitwellThis module tracks state changes internally and maintains derived 31fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwellvalues based on the current state. For this to work, the driver 32fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwellensure the following funciton is called whenever the state changes and 33fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwellthe swsetup module is 'awake': 34fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwell 35f9995b30756140724f41daf963fa06167912be7fKristian Høgsberg void _tnl_InvalidateState( struct gl_context *ctx, GLuint new_state ); 36fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwell 37fffc27015b60d4621316ef567a81c5c5dfcb182cKeith WhitwellThere is no explicit call to put the tnl module to sleep. Simply 38fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwellinstall other function pointers into all the vtxfmt dispatch slots, 39fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwelland (optionally) cease calling _tnl_InvalidateState(). 40fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwell 41fffc27015b60d4621316ef567a81c5c5dfcb182cKeith WhitwellCUSTOMIZATION 42fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwell 43fffc27015b60d4621316ef567a81c5c5dfcb182cKeith WhitwellThe module provides customizability through several mechanisms. The 44fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwellmost important is by allowing drivers to specify the pipeline through 45fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwellwhich vertex data is passed, including its eventual transfer to 46fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwellrasterization hardware (or software). 47fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwell 48fffc27015b60d4621316ef567a81c5c5dfcb182cKeith WhitwellThe default pipeline is specified in t_pipeline.c, and is usually a 49fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwellstarting point for driver pipelines. Some drivers will remove a stage 50fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwellwhere hardware provides support for the implemented operation (for 51e4344161bde2e24fcfba65d30d58f087bd8bf94dIan Romanickinstance fog where per-pixel hardware fog is available), 52e4344161bde2e24fcfba65d30d58f087bd8bf94dIan Romanickor add stages to shortcircuit latter operations (for 53fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwellexample taking advantage of hardware support for strips and other 54fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwellhigher-level primitives (for example the radeon driver). 55fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwell 56fffc27015b60d4621316ef567a81c5c5dfcb182cKeith WhitwellIn addition, the following functions provide further tweaks: 57fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwell 58fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwellextern void 59f9995b30756140724f41daf963fa06167912be7fKristian Høgsberg_tnl_need_projected_coords( struct gl_context *ctx, GLboolean flag ); 60fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwell 61fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwell - Direct the default vertex transformation stage to 62fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwell produce/not produce projected clip coordinates. 63fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwell 64fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwellextern void 65f9995b30756140724f41daf963fa06167912be7fKristian Høgsberg_tnl_need_dlist_loopback( struct gl_context *ctx, GLboolean flag ); 66fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwell 67fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwell - Direct the display list component of the tnl module to 68fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwell replay display lists as 'glVertex' type calls, rather than 69fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwell passing the display list data directly into the tnl pipeline 70fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwell mechanism. 71fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwell 72fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwell This allows display lists to be replayed by the tnl module 73fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwell even when the module is not strictly active. 74fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwell 75fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwell 76fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwellextern void 77f9995b30756140724f41daf963fa06167912be7fKristian Høgsberg_tnl_need_dlist_norm_lengths( struct gl_context *ctx, GLboolean flag ); 78fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwell 79fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwell - Direct the display list component to enable/disable caching 80fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwell 1/length values for display list normals. Doing so is 81fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwell ususally helpful when lighting is performed in software, but 82fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwell wasteful otherwise. 83fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwell 84fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwell 85fffc27015b60d4621316ef567a81c5c5dfcb182cKeith WhitwellDRIVER INTERFACE 86fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwell 87fffc27015b60d4621316ef567a81c5c5dfcb182cKeith WhitwellThe module itself offers a minimal driver interface: 88fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwell 89f9995b30756140724f41daf963fa06167912be7fKristian Høgsberg void (*RunPipeline)( struct gl_context *ctx ); 90fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwell 91fffc27015b60d4621316ef567a81c5c5dfcb182cKeith WhitwellNormally this is set to _tnl_RunPipeline(), however the driver can use 92fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwellthis hook to wrap checks or other code around this call. 93fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwell 94fffc27015b60d4621316ef567a81c5c5dfcb182cKeith WhitwellIn addition, the driver interface for the default render pipeline 95fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwellstage is housed in the tnl context struct (this could be cleaner). 96fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwell 97fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwell 98fffc27015b60d4621316ef567a81c5c5dfcb182cKeith WhitwellRENDER DRIVER INTERFACE 99fffc27015b60d4621316ef567a81c5c5dfcb182cKeith Whitwell 100fffc27015b60d4621316ef567a81c5c5dfcb182cKeith WhitwellSee t_context.h for the definition and explanation of this.