docs: Add all semantics to TGSI doc, regen.

4 files changed, 252 insertions, 19 deletions

diff --git a/src/gallium/docs/build/html/_sources/tgsi.txt b/src/gallium/docs/build/html/_sources/tgsi.txt
index 86c09046f7..12687f29dc 100644
--- a/src/gallium/docs/build/html/_sources/tgsi.txt
+++ b/src/gallium/docs/build/html/_sources/tgsi.txt
@@ -1180,11 +1180,92 @@ Declaration Semantic
   The meanings of the individual semantic names are explained in the following
   sections.
 
+TGSI_SEMANTIC_POSITION
+""""""""""""""""""""""
 
-FACE
-""""
+Position, sometimes known as HPOS or WPOS for historical reasons, is the
+location of the vertex in space, in ``(x, y, z, w)`` format. ``x``, ``y``, and ``z``
+are the Cartesian coordinates, and ``w`` is the homogenous coordinate and used
+for the perspective divide, if enabled.
 
-  Valid only in a fragment shader INPUT declaration.
+As a vertex shader output, position should be scaled to the viewport. When
+used in fragment shaders, position will ---
 
-  FACE.x is negative when the primitive is back facing. FACE.x is positive
-  when the primitive is front facing.
+XXX --- wait a minute. Should position be in [0,1] for x and y?
+
+XXX additionally, is there a way to configure the perspective divide? it's
+accelerated on most chipsets AFAIK...
+
+Position, if not specified, usually defaults to ``(0, 0, 0, 1)``, and can
+be partially specified as ``(x, y, 0, 1)`` or ``(x, y, z, 1)``.
+
+XXX usually? can we solidify that?
+
+TGSI_SEMANTIC_COLOR
+"""""""""""""""""""
+
+Colors are used to, well, color the primitives. Colors are always in
+``(r, g, b, a)`` format.
+
+If alpha is not specified, it defaults to 1.
+
+TGSI_SEMANTIC_BCOLOR
+""""""""""""""""""""
+
+Back-facing colors are only used for back-facing polygons, and are only valid
+in vertex shader outputs. After rasterization, all polygons are front-facing
+and COLOR and BCOLOR end up occupying the same slots in the fragment, so
+all BCOLORs effectively become regular COLORs in the fragment shader.
+
+TGSI_SEMANTIC_FOG
+"""""""""""""""""
+
+The fog coordinate historically has been used to replace the depth coordinate
+for generation of fog in dedicated fog blocks. Gallium, however, does not use
+dedicated fog acceleration, placing it entirely in the fragment shader
+instead.
+
+The fog coordinate should be written in ``(f, 0, 0, 1)`` format. Only the first
+component matters when writing from the vertex shader; the driver will ensure
+that the coordinate is in this format when used as a fragment shader input.
+
+TGSI_SEMANTIC_PSIZE
+"""""""""""""""""""
+
+PSIZE, or point size, is used to specify point sizes per-vertex. It should
+be in ``(p, n, x, f)`` format, where ``p`` is the point size, ``n`` is the minimum
+size, ``x`` is the maximum size, and ``f`` is the fade threshold.
+
+XXX this is arb_vp. is this what we actually do? should double-check...
+
+When using this semantic, be sure to set the appropriate state in the
+:ref:`rasterizer` first.
+
+TGSI_SEMANTIC_GENERIC
+"""""""""""""""""""""
+
+Generic semantics are nearly always used for texture coordinate attributes,
+in ``(s, t, r, q)`` format. ``t`` and ``r`` may be unused for certain kinds
+of lookups, and ``q`` is the level-of-detail bias for biased sampling.
+
+These attributes are called "generic" because they may be used for anything
+else, including parameters, texture generation information, or anything that
+can be stored inside a four-component vector.
+
+TGSI_SEMANTIC_NORMAL
+""""""""""""""""""""
+
+XXX no clue.
+
+TGSI_SEMANTIC_FACE
+""""""""""""""""""
+
+FACE is the facing bit, to store the facing information for the fragment
+shader. ``(f, 0, 0, 1)`` is the format. The first component will be positive
+when the fragment is front-facing, and negative when the component is
+back-facing.
+
+TGSI_SEMANTIC_EDGEFLAG
+""""""""""""""""""""""
+
+XXX no clue
diff --git a/src/gallium/docs/build/html/searchindex.js b/src/gallium/docs/build/html/searchindex.js
index c3c0b876ea..0e3f2bb4a2 100644
--- a/src/gallium/docs/build/html/searchindex.js
+++ b/src/gallium/docs/build/html/searchindex.js
@@ -1 +1 @@
-Search.setIndex({desctypes:{},terms:{represent:4,all:[4,9,11],concept:9,edg:2,queri:[4,9],particular:9,four:[4,10],scalar:4,per:5,abil:9,follow:[4,9],depend:5,intermedi:4,ps_2_x:4,those:4,logarithm:4,sourc:[4,9],normalis:4,straightforward:7,fals:4,set_vertex_el:9,lrp:4,fan:5,partialx:4,level:10,pk4b:4,list:6,"884467e":[],emul:9,prefilt:10,cosin:4,sine:4,small:9,div:4,round:4,cmp:4,dimens:10,impli:5,flr:4,up4b:4,sign:4,tex:4,second:[4,5,11],pass:[1,11],light_twosid:5,zfail_op:11,index:0,what:[0,7,8],sprite_coord_mod:5,sub:4,compar:4,neg:4,section:[4,9],current:9,delet:9,rgba:[9,10],method:[0,3,9],themselv:5,deriv:4,absolut:4,coeffici:4,inher:4,path:9,vertic:5,modifi:9,sinc:4,valu:[4,9,11],trunc:4,line_stipple_factor:5,search:0,shift:4,vbo:[],shader:[0,1,4,5,6,9,11],permit:[5,9],weird:10,gourard:5,semant:4,txl:4,"boolean":3,txf:4,modul:0,txd:4,sgt:4,src2:4,src0:4,api:[1,4,7,10],brk:4,is_texture_referenc:9,visibl:5,oval:5,sge:4,bra:4,encapsul:7,gl_rasterization_rul:5,from:[4,5,9,10],offset_unit:5,subtract:4,regist:4,two:[4,6,9,11],program:4,call:[4,9],get_paramf:3,stage:4,type:6,more:9,desir:1,get_nam:3,raster:[0,1,5,9],pipe_primitive_quad:5,flag:5,indic:[0,4],fill_ccw:5,unpack:4,point_size_min:5,must:4,poly_smooth:5,graphic:[4,7],retriev:9,setup:3,work:1,obvious:5,can:[1,4,3,9],cal:4,purpos:4,root:4,fetch:4,control:[11,8,5,9,10],create_blend_st:9,pipe_surfac:9,templat:3,minimum:[4,5,10],want:9,dp2a:4,unsign:4,occur:4,gl_nv_vertex_program:4,alwai:[11,5,10],point_size_per_vertex:5,multipl:[2,9],divid:4,anoth:9,write:[7,9,11],how:[4,5,9,10],flatshad:[1,5],simpl:9,sin:4,"42101e":[],product:4,sne:4,resourc:9,max:4,after:10,cso:[0,1,9],set_constant_buff:9,mad:4,mai:[5,9],end:4,fail_op:11,pipe_stencil_op:11,principl:1,essenti:7,third:4,bind:9,counter:4,element:5,endprim:4,inform:2,valuemask:11,order:11,rotat:5,over:9,move:[4,9],through:[5,11],sqrt:[],still:5,paramet:3,group:9,directli:9,bypass:5,main:5,easier:9,non:9,"return":[1,4,3],greater:4,thei:[1,11,5,9,10],fragment:[4,8,5,9,11],initi:9,get_vendor:3,"break":4,line_smooth:5,cull_mod:5,front:4,nop:4,introduct:[0,7],name:[3,4,9],separ:9,token:[0,4,6],each:[5,10],side:11,doxi:10,offset_ccw:5,clamp:[4,10],chunk:5,continu:4,frac:4,special:[4,9],out:[1,11,10],variabl:9,dst:4,ret:4,content:0,vector:4,rel:4,hardwar:[7,5,11],got:3,linear:4,offset_cw:5,given:3,compare_func:10,endsub:4,base:4,begin_queri:9,"_rasterizer_st":9,reusabl:1,endrep:4,filter:10,turn:5,get_param:3,clump:11,first:[4,5],oper:[4,9,11],glsl:4,rang:10,max_lod:10,render:[8,9],carri:11,independ:3,restrict:4,clear:9,instruct:[0,4],done:11,size:[4,5],differ:[4,5],stencil:[0,1,9,11],exponenti:4,tradition:11,too:9,circl:5,scheme:9,moar:[3,5],store:11,nrm4:4,min_img_filt:10,option:[4,5,10],pipe_tex_filt:10,specifi:5,create_queri:9,part:[1,4,3],than:4,line_stipple_en:5,target:[4,8],keyword:4,provid:[7,9],remov:4,see:3,structur:11,texel:[4,10],stippl:5,str:4,opaqu:1,posit:4,rcc:4,result:[8,9],pre:5,fashion:7,clip:5,pk4ub:4,ani:[1,9],"_blend_stat":9,bitfield:5,subroutin:4,max_anisotropi:10,txb:4,manner:[3,7],have:[11,5,9,10],tabl:0,need:5,seem:9,"null":9,bitwis:4,techniqu:2,unresolv:8,alias:[2,5],destroi:9,fill_cw:5,note:[1,4,5],ex2:4,take:2,set_viewport_st:9,pipe_func:11,noth:4,singl:9,pipelin:[4,5,9],xor:4,shade:5,normal:10,buffer:[2,8,9,11],object:[1,7,3,9],most:[5,9],sfl:4,mipmap:10,alpha:[0,1,9,11],pipe_primitive_polygon:5,segment:5,tradit:10,pk2h:4,nail:9,tgsi:[0,4],face:4,pipe:4,declar:4,determin:5,pk2u:4,left:4,blend:[0,1,8,9],sum:4,dot:4,end_queri:9,popa:4,destroy_blend_st:9,wrap_:10,dst0:4,trivial:9,access:9,onli:[4,9],dp4:4,dp3:4,dp2:4,front_wind:5,point_sprit:5,should:[8,5],busi:9,endloop:4,lit:4,variou:9,get:3,set_scissor_st:9,stop:9,ceil:4,mul:4,tungsten:4,ssg:4,tgsi_token:6,tbd:4,set_fragment_sampler_textur:9,shr:4,enabl:[5,9,11],draw_el:9,"default":4,statist:9,contain:4,anisotrop:10,shl:4,valid:4,dph:4,arr:4,set:[0,4,5,9,10],set_framebuffer_st:9,seq:4,smooth:[2,5],ara:4,msaa:[2,5],wrap_t:10,wrap_r:10,fail:11,arl:4,purest:9,modulu:4,project:4,pattern:5,label:4,state:[1,5,8,9,10,11],between:4,"import":[4,5],subscript:4,triplet:9,screen:[0,3],min_mip_filt:10,entir:5,is_buffer_referenc:9,lod_bia:10,addit:9,both:[9,11],last:5,framebuff:9,x2d:4,region:9,equal:4,pixel:5,min_lod:10,context:[0,1,3,9],line_last_pixel:5,mani:10,destroy_queri:9,load:[4,10],undocu:[8,5,10],point:[3,5,9],color:[5,10],pow:4,address:4,pop:4,distinguish:4,callnz:4,reciproc:4,anti:[2,5],provok:5,lg2:4,asdf:[],light:4,endif:4,devic:[3,7,9],three:[4,11],been:11,compon:4,get_query_result:9,treat:10,basic:2,bgnsub:4,up4ub:4,sprite:5,nrm:4,normalized_coord:10,xxx:[3,4,5,8,10,11],coordin:[4,10],zero:4,minifi:10,togeth:11,func:11,predic:4,bgnloop:4,sad:4,present:9,multi:2,ident:4,slt:4,servic:7,properti:1,batch:9,rectangular:5,behavior:8,glossari:[2,0],sle:4,loop:4,pack:[4,9],gl_nv_vertex_program2:4,cont:4,set_edgeflag:9,endfor:4,destin:[4,9],txq:4,primit:[4,5],"_vs_state":9,sever:[7,5],set_blend_color:9,surface_fil:9,welcom:0,bind_fragment_sampler_st:9,perform:9,make:9,cross:4,same:[4,9],member:[1,5,6,8,10,11],handl:[1,9],compare_mod:10,instanc:9,zpass_op:11,document:[0,11],difficult:9,finish:9,nest:9,driver:[4,7,9],effect:[1,5,10],mov:4,capabl:4,rais:[],kil:4,stack:4,squar:4,multisampl:5,off:[8,5],center:5,surface_copi:9,min:4,aisl:4,scissor:5,exampl:9,reflect:4,poly_stipple_en:5,thi:[2,4,5,8,9,10],interpol:[4,5],set_clip_st:9,dimension:10,i2f:4,usual:5,explan:[0,4],distanc:4,identifi:3,execut:11,less:4,kilp:4,up2u:4,up2h:4,tcl:5,simpli:5,semanticnam:4,breakc:4,languag:4,begin:4,gl_nv_geometry_program4:4,expos:10,except:5,add:[4,9],cleanup:4,exercis:9,sampler:[0,1,9,10],els:4,mod:4,bypass_vs_clip_and_viewport:[1,5],match:4,pipe_tex_wrap:10,vendor:3,which:[1,7],format:[3,9],read:9,agnost:7,piec:9,bia:[4,10],bgnfor:4,magnifi:10,amp:11,bit:[4,5],truncat:4,apart:9,like:9,specif:[1,3,9,5],integ:[3,4],point_siz:5,src1:4,either:[4,9],output:4,page:0,mag_img_filt:10,refin:10,pipe_primitive_quad_strip:5,right:4,draw_range_el:9,some:[9,10],back:[3,4],pusha:4,opcod:4,sampl:[2,10],flush:9,guarante:9,bore:3,textur:[3,4,9,10],ddy:4,ddx:4,partiali:4,though:9,overlap:9,point_smooth:5,multipli:4,cnd:4,tracker:9,larg:7,unit:10,condit:4,txp:4,refer:[11,10],core:[1,7],run:5,rsq:4,border_color:10,ifc:4,"_depth_stencil_alpha_st":9,appli:10,describ:[4,9],writemask:11,src:4,actual:[5,11],gallium:[0,1,4,7,6],semanticindex:4,bind_vertex_sampler_st:9,set_vertex_buff:9,stand:9,awai:5,discard:[4,11],approxim:4,mean:4,disabl:10,"final":[8,9],"float":[3,4],bound:[1,9,10],down:9,explain:4,wrap:10,chang:[5,9],mere:5,flatshade_first:[1,5],log:4,lod:[4,10],support:[4,6],rcp:4,transform:[4,5],xpd:4,avail:9,width:5,set_polygon_stippl:9,interfac:9,fraction:4,individu:[4,10],select:10,"function":[4,9,11],homogen:4,blend_en:8,set_vertex_sampler_textur:9,point_size_max:5,link:4,blit:9,line:5,"true":4,viewport:5,gl_nv_gpu_program4:4,notat:10,flavour:9,input:4,draw_arrai:9,whether:[11,5,10],wish:5,caller:5,bind_blend_st:9,maximum:[4,5,10],"abstract":9,line_stipple_pattern:5,emit:4,offset_scal:5,gather:9,constant:[1,4],creat:[1,3,9],classic:9,certain:11,dure:11,rfl:4,repres:[3,9],implement:5,file:4,fill:[1,9],polygon:[2,5],floor:4,when:[4,5,9,10],detail:10,power:4,field:4,other:[0,4],lookup:4,futur:9,branch:4,test:[5,11],ref_valu:11,draw:9,repeat:4,exp:4,is_format_support:3,symbol:[0,4],vertex:[5,9],surfac:9,consid:4,receiv:11,blitter:9,algorithm:5,rule:5,pipe_primitive_triangle_fan:5,depth:[2,0,1,9,11],"_fs_state":9,potenti:4,time:[1,4],push:4,line_width:5,rep:4,texture_cr:3},titles:["Welcome to Gallium’s documentation!","CSO","Glossary","Screen","TGSI","Rasterizer","Shader","Introduction","Blend","Context","Sampler","Depth, Stencil, & Alpha"],modules:{},descrefs:{},filenames:["index","cso","glossary","screen","tgsi","cso/rasterizer","cso/shader","intro","cso/blend","context","cso/sampler","cso/dsa"]})
\ No newline at end of file
+Search.setIndex({desctypes:{},terms:{represent:4,all:[4,9,11],concept:9,partial:4,edg:2,queri:[4,9],particular:9,four:[4,10],scalar:4,per:[4,5],abil:9,follow:[4,9],locat:4,depend:5,name:[3,4,9],intermedi:4,ps_2_x:4,those:4,unit:10,logarithm:4,sourc:[4,9],normalis:4,straightforward:7,fals:4,set_vertex_el:9,lrp:4,fan:5,partialx:4,level:[4,10],pk4b:4,list:6,emul:9,prefilt:10,cosin:4,small:9,div:4,round:4,cmp:4,dimens:10,impli:5,flr:4,tgsi_semantic_posit:4,up4b:4,sign:4,tex:4,second:[4,5,11],pass:[1,11],light_twosid:5,zfail_op:11,index:0,what:[8,0,4,7],xor:4,sub:4,compar:4,neg:4,section:[4,9],access:9,delet:9,rgba:[9,10],method:[0,3,9],themselv:5,deriv:4,gener:4,coeffici:4,psize:4,becom:4,inher:4,path:9,vertic:5,modifi:9,sinc:4,valu:[4,9,11],trunc:4,line_stipple_factor:5,search:0,shift:4,current:9,vbo:[],shader:[0,1,4,5,6,9,11],permit:[5,9],weird:10,gourard:5,endrep:4,semant:4,txl:4,"boolean":3,txf:4,modul:0,txd:4,sgt:4,textur:[3,4,9,10],src2:4,src0:4,api:[1,4,7,10],brk:4,is_texture_referenc:9,visibl:5,oval:5,sge:4,select:10,encapsul:7,gl_rasterization_rul:5,from:[4,5,9,10],offset_unit:5,subtract:4,doubl:4,regist:4,two:[4,6,9,11],program:4,call:[4,9],get_paramf:3,stage:4,type:6,more:9,desir:1,get_nam:3,raster:[0,1,4,5,9],pipe_primitive_quad:5,clue:4,flag:5,indic:[0,4],fill_ccw:5,known:4,unpack:4,point_size_min:5,must:4,poly_smooth:5,graphic:[4,7],retriev:9,setup:3,work:1,obvious:5,can:[1,4,3,9],cal:4,purpos:4,root:4,fetch:4,control:[11,8,5,9,10],create_blend_st:9,pipe_surfac:9,templat:3,minimum:[4,5,10],want:9,dp2a:4,unsign:4,occur:4,nearli:4,gl_nv_vertex_program:4,alwai:[11,4,5,10],point_size_per_vertex:5,multipl:[2,9],divid:4,anoth:9,write:[4,7,9,11],how:[4,5,9,10],flatshad:[1,5],instead:4,simpl:9,sin:4,"42101e":[],product:4,sne:4,resourc:9,max:4,after:[4,10],cso:[0,1,9],set_constant_buff:9,mad:4,mai:[4,5,9],end:4,fail_op:11,pipe_stencil_op:11,principl:1,essenti:7,third:4,bind:9,counter:4,element:5,endprim:4,inform:[2,4],valuemask:11,order:11,rotat:5,over:9,move:[4,9],becaus:4,through:[5,11],sqrt:[],still:5,tgsi_semantic_bcolor:4,paramet:[3,4],group:9,directli:9,bypass:5,main:5,easier:9,non:9,"return":[1,4,3],greater:4,thei:[1,4,5,9,10,11],fragment:[4,8,5,9,11],initi:9,get_vendor:3,"break":4,line_smooth:5,cull_mod:5,front:4,nop:4,introduct:[0,7],"884467e":[],anyth:4,perspect:4,separ:9,token:[0,4,6],each:[5,10],side:11,doxi:10,offset_ccw:5,clamp:[4,10],replac:4,chunk:5,continu:4,ensur:4,frac:4,special:[4,9],out:[1,11,10],variabl:9,space:4,dst:4,ret:4,content:0,vector:4,rel:4,hardwar:[7,5,11],got:3,linear:4,insid:4,offset_cw:5,given:3,compare_func:10,endsub:4,reason:4,base:4,begin_queri:9,"_rasterizer_st":9,reusabl:1,wai:4,where:4,filter:10,turn:5,wpo:4,place:4,get_param:3,clump:11,first:[4,5],oper:[4,9,11],glsl:4,rang:10,max_lod:10,render:[8,9],carri:11,independ:3,restrict:4,instruct:[0,4],done:11,tgsi_semantic_gener:4,light:4,size:[4,5],differ:[4,5],stencil:[0,1,9,11],exponenti:4,sometim:4,tradition:11,too:9,circl:5,scheme:9,moar:[3,5],store:[4,11],nrm4:4,min_img_filt:10,option:[4,5,10],pipe_tex_filt:10,specifi:[4,5],create_queri:9,part:[1,4,3],than:4,line_stipple_en:5,kind:4,target:[4,8],keyword:4,provid:[7,9],remov:4,see:3,structur:11,texel:[4,10],stippl:5,matter:4,str:4,opaqu:1,posit:4,minut:4,result:[8,9],pre:5,fashion:7,clip:5,pk4ub:4,ani:[1,9],"_blend_stat":9,bitfield:5,subroutin:4,max_anisotropi:10,txb:4,manner:[3,7],have:[11,5,9,10],tabl:0,need:5,dedic:4,"null":9,arb_vp:4,bitwis:4,techniqu:2,unresolv:8,alias:[2,5],destroi:9,fill_cw:5,note:[1,4,5],ex2:4,take:2,set_viewport_st:9,pipe_func:11,noth:4,singl:9,pipelin:[4,5,9],sure:4,shade:5,normal:10,buffer:[2,8,9,11],object:[1,7,3,9],most:[4,5,9],sfl:4,regular:4,mipmap:10,sprite_coord_mod:5,pipe_primitive_polygon:5,segment:5,tgsi_semantic_fog:4,tradit:10,pk2h:4,clear:9,tgsi:[0,4],face:4,pipe:4,declar:4,tracker:9,determin:5,pk2u:4,left:4,blend:[0,1,8,9],sum:4,dot:4,end_queri:9,popa:4,destroy_blend_st:9,wrap_:10,dst0:4,threshold:4,hpo:4,trivial:9,slot:4,absolut:4,onli:[4,9],dp4:4,dp3:4,dp2:4,front_wind:5,point_sprit:5,configur:4,written:4,should:[4,8,5],busi:9,endloop:4,lit:4,unus:4,variou:9,get:3,set_scissor_st:9,stop:9,tgsi_semantic_color:4,ceil:4,mul:4,tungsten:4,ssg:4,tgsi_token:6,tbd:4,set_fragment_sampler_textur:9,shr:4,enabl:[4,5,9,11],draw_el:9,"default":4,statist:9,contain:4,anisotrop:10,shl:4,valid:4,dph:4,arr:4,set:[0,4,5,9,10],set_framebuffer_st:9,seq:4,smooth:[2,5],tgsi_semantic_edgeflag:4,ara:4,msaa:[2,5],wrap_t:10,wrap_r:10,fail:11,arl:4,purest:9,modulu:4,project:4,pattern:5,label:4,state:[1,4,5,8,9,10,11],between:4,"import":[4,5],subscript:4,attribut:4,triplet:9,screen:[0,3],min_mip_filt:10,entir:[4,5],chipset:4,is_buffer_referenc:9,lod_bia:10,addit:9,both:[9,11],last:5,framebuff:9,x2d:4,region:9,equal:4,min_lod:10,context:[0,1,3,9],line_last_pixel:5,mani:10,destroy_queri:9,load:[4,10],acceler:4,undocu:[8,5,10],point:[3,4,5,9],color:[4,5,10],pow:4,address:4,pop:4,distinguish:4,callnz:4,reciproc:4,anti:[2,5],provok:5,lg2:4,asdf:[],sine:4,endif:4,addition:4,devic:[3,7,9],three:[4,11],been:[4,11],compon:4,get_query_result:9,treat:10,basic:2,wait:4,up4ub:4,sprite:5,nrm:4,normalized_coord:10,xxx:[3,4,5,8,10,11],fade:4,coordin:[4,10],zero:4,minifi:10,texture_cr:3,func:11,predic:4,bgnloop:4,sad:4,present:9,multi:2,ident:4,slt:4,servic:7,properti:1,histor:4,rectangular:5,behavior:8,glossari:[2,0],sle:4,howev:4,loop:4,pack:[4,9],gl_nv_vertex_program2:4,cont:4,set_edgeflag:9,endfor:4,destin:[4,9],txq:4,bias:4,primit:[4,5],"_vs_state":9,sever:[7,5],set_blend_color:9,surface_fil:9,welcom:0,bind_fragment_sampler_st:9,perform:9,make:9,nail:9,cross:4,same:[4,9],member:[1,5,6,8,10,11],handl:[1,9],compare_mod:10,instanc:9,zpass_op:11,document:[0,11],difficult:9,finish:9,nest:9,driver:[4,7,9],effect:[1,4,5,10],mov:4,capabl:4,rais:[],kil:4,stack:4,squar:4,multisampl:5,appropri:4,off:[8,5],center:5,surface_copi:9,min:4,well:4,bgnsub:4,aisl:4,scissor:5,exampl:9,reflect:4,poly_stipple_en:5,thi:[2,4,5,8,9,10],interpol:[4,5],set_clip_st:9,dimension:10,i2f:4,usual:[4,5],explan:[0,4],distanc:4,identifi:3,execut:11,less:4,kilp:4,up2u:4,up2h:4,tcl:5,simpli:5,semanticnam:4,breakc:4,languag:4,begin:4,gl_nv_geometry_program4:4,expos:10,afaik:4,except:5,seem:9,add:[4,9],cleanup:4,exercis:9,sampler:[0,1,9,10],els:4,mod:4,bypass_vs_clip_and_viewport:[1,5],match:4,pipe_tex_wrap:10,vendor:3,which:[1,7],format:[3,4,9],read:9,agnost:7,piec:9,bia:[4,10],bgnfor:4,magnifi:10,amp:11,bit:[4,5],truncat:4,apart:9,like:9,specif:[1,3,9,5],integ:[3,4],point_siz:5,src1:4,either:[4,9],output:4,page:0,mag_img_filt:10,refin:10,pipe_primitive_quad_strip:5,right:4,draw_range_el:9,some:[9,10],blend_en:8,pusha:4,opcod:4,sampl:[2,4,10],bcolor:4,flush:9,guarante:9,bore:3,pixel:5,ddy:4,ddx:4,partiali:4,though:9,overlap:9,point_smooth:5,multipli:4,cnd:4,fog:4,larg:7,bra:4,condit:4,txp:4,refer:[11,10],core:[1,7],tgsi_semantic_ps:4,run:5,rsq:4,border_color:10,ifc:4,"_depth_stencil_alpha_st":9,appli:10,describ:[4,9],writemask:11,src:4,actual:[4,5,11],solidifi:4,gallium:[0,1,4,7,6],semanticindex:4,bind_vertex_sampler_st:9,set_vertex_buff:9,stand:9,awai:5,discard:[4,11],approxim:4,mean:4,disabl:10,block:4,"final":[8,9],"float":[3,4],bound:[1,9,10],down:9,explain:4,alpha:[0,1,4,9,11],wrap:10,chang:[5,9],batch:9,mere:5,flatshade_first:[1,5],occupi:4,log:4,lod:[4,10],support:[4,6],rcp:4,transform:[4,5],xpd:4,avail:9,width:5,set_polygon_stippl:9,interfac:9,includ:4,fraction:4,cartesian:4,individu:[4,10],rcc:4,"function":[4,9,11],homogen:4,back:[3,4],tgsi_semantic_fac:4,set_vertex_sampler_textur:9,point_size_max:5,link:4,blit:9,line:5,"true":4,viewport:[4,5],gl_nv_gpu_program4:4,notat:10,flavour:9,input:4,draw_arrai:9,whether:[11,5,10],wish:5,caller:5,bind_blend_st:9,maximum:[4,5,10],"abstract":9,line_stipple_pattern:5,tgsi_semantic_norm:4,emit:4,offset_scal:5,gather:9,constant:[1,4],creat:[1,3,9],classic:9,certain:[4,11],dure:11,rfl:4,repres:[3,9],implement:5,file:4,doe:4,check:4,fill:[1,9],polygon:[2,4,5],floor:4,when:[4,5,9,10],detail:[4,10],power:4,field:4,other:[0,4],lookup:4,futur:9,branch:4,test:[5,11],ref_valu:11,draw:9,repeat:4,exp:4,is_format_support:3,symbol:[0,4],vertex:[4,5,9],surfac:9,scale:4,consid:4,receiv:11,blitter:9,algorithm:5,rule:5,pipe_primitive_triangle_fan:5,depth:[0,1,2,4,9,11],"_fs_state":9,potenti:4,time:[1,4],push:4,line_width:5,rep:4,togeth:11},titles:["Welcome to Gallium’s documentation!","CSO","Glossary","Screen","TGSI","Rasterizer","Shader","Introduction","Blend","Context","Sampler","Depth, Stencil, & Alpha"],modules:{},descrefs:{},filenames:["index","cso","glossary","screen","tgsi","cso/rasterizer","cso/shader","intro","cso/blend","context","cso/sampler","cso/dsa"]})
\ No newline at end of file
diff --git a/src/gallium/docs/build/html/tgsi.html b/src/gallium/docs/build/html/tgsi.html
index 0dac00f25e..7954e1de40 100644
--- a/src/gallium/docs/build/html/tgsi.html
+++ b/src/gallium/docs/build/html/tgsi.html
@@ -861,13 +861,76 @@ is 0.</p>
 <p>The meanings of the individual semantic names are explained in the following
 sections.</p>
 </blockquote>
-<div class="section" id="face">
-<h4>FACE<a class="headerlink" href="#face" title="Permalink to this headline">¶</a></h4>
-<blockquote>
-<p>Valid only in a fragment shader INPUT declaration.</p>
-<p>FACE.x is negative when the primitive is back facing. FACE.x is positive
-when the primitive is front facing.</p>
-</blockquote>
+<div class="section" id="tgsi-semantic-position">
+<h4>TGSI_SEMANTIC_POSITION<a class="headerlink" href="#tgsi-semantic-position" title="Permalink to this headline">¶</a></h4>
+<p>Position, sometimes known as HPOS or WPOS for historical reasons, is the
+location of the vertex in space, in <tt class="docutils literal"><span class="pre">(x,</span> <span class="pre">y,</span> <span class="pre">z,</span> <span class="pre">w)</span></tt> format. <tt class="docutils literal"><span class="pre">x</span></tt>, <tt class="docutils literal"><span class="pre">y</span></tt>, and <tt class="docutils literal"><span class="pre">z</span></tt>
+are the Cartesian coordinates, and <tt class="docutils literal"><span class="pre">w</span></tt> is the homogenous coordinate and used
+for the perspective divide, if enabled.</p>
+<p>As a vertex shader output, position should be scaled to the viewport. When
+used in fragment shaders, position will &#8212;</p>
+<p>XXX &#8212; wait a minute. Should position be in [0,1] for x and y?</p>
+<p>XXX additionally, is there a way to configure the perspective divide? it&#8217;s
+accelerated on most chipsets AFAIK...</p>
+<p>Position, if not specified, usually defaults to <tt class="docutils literal"><span class="pre">(0,</span> <span class="pre">0,</span> <span class="pre">0,</span> <span class="pre">1)</span></tt>, and can
+be partially specified as <tt class="docutils literal"><span class="pre">(x,</span> <span class="pre">y,</span> <span class="pre">0,</span> <span class="pre">1)</span></tt> or <tt class="docutils literal"><span class="pre">(x,</span> <span class="pre">y,</span> <span class="pre">z,</span> <span class="pre">1)</span></tt>.</p>
+<p>XXX usually? can we solidify that?</p>
+</div>
+<div class="section" id="tgsi-semantic-color">
+<h4>TGSI_SEMANTIC_COLOR<a class="headerlink" href="#tgsi-semantic-color" title="Permalink to this headline">¶</a></h4>
+<p>Colors are used to, well, color the primitives. Colors are always in
+<tt class="docutils literal"><span class="pre">(r,</span> <span class="pre">g,</span> <span class="pre">b,</span> <span class="pre">a)</span></tt> format.</p>
+<p>If alpha is not specified, it defaults to 1.</p>
+</div>
+<div class="section" id="tgsi-semantic-bcolor">
+<h4>TGSI_SEMANTIC_BCOLOR<a class="headerlink" href="#tgsi-semantic-bcolor" title="Permalink to this headline">¶</a></h4>
+<p>Back-facing colors are only used for back-facing polygons, and are only valid
+in vertex shader outputs. After rasterization, all polygons are front-facing
+and COLOR and BCOLOR end up occupying the same slots in the fragment, so
+all BCOLORs effectively become regular COLORs in the fragment shader.</p>
+</div>
+<div class="section" id="tgsi-semantic-fog">
+<h4>TGSI_SEMANTIC_FOG<a class="headerlink" href="#tgsi-semantic-fog" title="Permalink to this headline">¶</a></h4>
+<p>The fog coordinate historically has been used to replace the depth coordinate
+for generation of fog in dedicated fog blocks. Gallium, however, does not use
+dedicated fog acceleration, placing it entirely in the fragment shader
+instead.</p>
+<p>The fog coordinate should be written in <tt class="docutils literal"><span class="pre">(f,</span> <span class="pre">0,</span> <span class="pre">0,</span> <span class="pre">1)</span></tt> format. Only the first
+component matters when writing from the vertex shader; the driver will ensure
+that the coordinate is in this format when used as a fragment shader input.</p>
+</div>
+<div class="section" id="tgsi-semantic-psize">
+<h4>TGSI_SEMANTIC_PSIZE<a class="headerlink" href="#tgsi-semantic-psize" title="Permalink to this headline">¶</a></h4>
+<p>PSIZE, or point size, is used to specify point sizes per-vertex. It should
+be in <tt class="docutils literal"><span class="pre">(p,</span> <span class="pre">n,</span> <span class="pre">x,</span> <span class="pre">f)</span></tt> format, where <tt class="docutils literal"><span class="pre">p</span></tt> is the point size, <tt class="docutils literal"><span class="pre">n</span></tt> is the minimum
+size, <tt class="docutils literal"><span class="pre">x</span></tt> is the maximum size, and <tt class="docutils literal"><span class="pre">f</span></tt> is the fade threshold.</p>
+<p>XXX this is arb_vp. is this what we actually do? should double-check...</p>
+<p>When using this semantic, be sure to set the appropriate state in the
+<a class="reference external" href="cso/rasterizer.html#rasterizer"><em>Rasterizer</em></a> first.</p>
+</div>
+<div class="section" id="tgsi-semantic-generic">
+<h4>TGSI_SEMANTIC_GENERIC<a class="headerlink" href="#tgsi-semantic-generic" title="Permalink to this headline">¶</a></h4>
+<p>Generic semantics are nearly always used for texture coordinate attributes,
+in <tt class="docutils literal"><span class="pre">(s,</span> <span class="pre">t,</span> <span class="pre">r,</span> <span class="pre">q)</span></tt> format. <tt class="docutils literal"><span class="pre">t</span></tt> and <tt class="docutils literal"><span class="pre">r</span></tt> may be unused for certain kinds
+of lookups, and <tt class="docutils literal"><span class="pre">q</span></tt> is the level-of-detail bias for biased sampling.</p>
+<p>These attributes are called &#8220;generic&#8221; because they may be used for anything
+else, including parameters, texture generation information, or anything that
+can be stored inside a four-component vector.</p>
+</div>
+<div class="section" id="tgsi-semantic-normal">
+<h4>TGSI_SEMANTIC_NORMAL<a class="headerlink" href="#tgsi-semantic-normal" title="Permalink to this headline">¶</a></h4>
+<p>XXX no clue.</p>
+</div>
+<div class="section" id="tgsi-semantic-face">
+<h4>TGSI_SEMANTIC_FACE<a class="headerlink" href="#tgsi-semantic-face" title="Permalink to this headline">¶</a></h4>
+<p>FACE is the facing bit, to store the facing information for the fragment
+shader. <tt class="docutils literal"><span class="pre">(f,</span> <span class="pre">0,</span> <span class="pre">0,</span> <span class="pre">1)</span></tt> is the format. The first component will be positive
+when the fragment is front-facing, and negative when the component is
+back-facing.</p>
+</div>
+<div class="section" id="tgsi-semantic-edgeflag">
+<h4>TGSI_SEMANTIC_EDGEFLAG<a class="headerlink" href="#tgsi-semantic-edgeflag" title="Permalink to this headline">¶</a></h4>
+<p>XXX no clue</p>
 </div>
 </div>
 </div>
@@ -898,7 +961,15 @@ when the primitive is front facing.</p>
 </li>
 <li><a class="reference external" href="#other-tokens">Other tokens</a><ul>
 <li><a class="reference external" href="#declaration-semantic">Declaration Semantic</a><ul>
-<li><a class="reference external" href="#face">FACE</a></li>
+<li><a class="reference external" href="#tgsi-semantic-position">TGSI_SEMANTIC_POSITION</a></li>
+<li><a class="reference external" href="#tgsi-semantic-color">TGSI_SEMANTIC_COLOR</a></li>
+<li><a class="reference external" href="#tgsi-semantic-bcolor">TGSI_SEMANTIC_BCOLOR</a></li>
+<li><a class="reference external" href="#tgsi-semantic-fog">TGSI_SEMANTIC_FOG</a></li>
+<li><a class="reference external" href="#tgsi-semantic-psize">TGSI_SEMANTIC_PSIZE</a></li>
+<li><a class="reference external" href="#tgsi-semantic-generic">TGSI_SEMANTIC_GENERIC</a></li>
+<li><a class="reference external" href="#tgsi-semantic-normal">TGSI_SEMANTIC_NORMAL</a></li>
+<li><a class="reference external" href="#tgsi-semantic-face">TGSI_SEMANTIC_FACE</a></li>
+<li><a class="reference external" href="#tgsi-semantic-edgeflag">TGSI_SEMANTIC_EDGEFLAG</a></li>
 </ul>
 </li>
 </ul>
diff --git a/src/gallium/docs/source/tgsi.rst b/src/gallium/docs/source/tgsi.rst
index 86c09046f7..12687f29dc 100644
--- a/src/gallium/docs/source/tgsi.rst
+++ b/src/gallium/docs/source/tgsi.rst
@@ -1180,11 +1180,92 @@ Declaration Semantic
   The meanings of the individual semantic names are explained in the following
   sections.
 
+TGSI_SEMANTIC_POSITION
+""""""""""""""""""""""
 
-FACE
-""""
+Position, sometimes known as HPOS or WPOS for historical reasons, is the
+location of the vertex in space, in ``(x, y, z, w)`` format. ``x``, ``y``, and ``z``
+are the Cartesian coordinates, and ``w`` is the homogenous coordinate and used
+for the perspective divide, if enabled.
 
-  Valid only in a fragment shader INPUT declaration.
+As a vertex shader output, position should be scaled to the viewport. When
+used in fragment shaders, position will ---
 
-  FACE.x is negative when the primitive is back facing. FACE.x is positive
-  when the primitive is front facing.
+XXX --- wait a minute. Should position be in [0,1] for x and y?
+
+XXX additionally, is there a way to configure the perspective divide? it's
+accelerated on most chipsets AFAIK...
+
+Position, if not specified, usually defaults to ``(0, 0, 0, 1)``, and can
+be partially specified as ``(x, y, 0, 1)`` or ``(x, y, z, 1)``.
+
+XXX usually? can we solidify that?
+
+TGSI_SEMANTIC_COLOR
+"""""""""""""""""""
+
+Colors are used to, well, color the primitives. Colors are always in
+``(r, g, b, a)`` format.
+
+If alpha is not specified, it defaults to 1.
+
+TGSI_SEMANTIC_BCOLOR
+""""""""""""""""""""
+
+Back-facing colors are only used for back-facing polygons, and are only valid
+in vertex shader outputs. After rasterization, all polygons are front-facing
+and COLOR and BCOLOR end up occupying the same slots in the fragment, so
+all BCOLORs effectively become regular COLORs in the fragment shader.
+
+TGSI_SEMANTIC_FOG
+"""""""""""""""""
+
+The fog coordinate historically has been used to replace the depth coordinate
+for generation of fog in dedicated fog blocks. Gallium, however, does not use
+dedicated fog acceleration, placing it entirely in the fragment shader
+instead.
+
+The fog coordinate should be written in ``(f, 0, 0, 1)`` format. Only the first
+component matters when writing from the vertex shader; the driver will ensure
+that the coordinate is in this format when used as a fragment shader input.
+
+TGSI_SEMANTIC_PSIZE
+"""""""""""""""""""
+
+PSIZE, or point size, is used to specify point sizes per-vertex. It should
+be in ``(p, n, x, f)`` format, where ``p`` is the point size, ``n`` is the minimum
+size, ``x`` is the maximum size, and ``f`` is the fade threshold.
+
+XXX this is arb_vp. is this what we actually do? should double-check...
+
+When using this semantic, be sure to set the appropriate state in the
+:ref:`rasterizer` first.
+
+TGSI_SEMANTIC_GENERIC
+"""""""""""""""""""""
+
+Generic semantics are nearly always used for texture coordinate attributes,
+in ``(s, t, r, q)`` format. ``t`` and ``r`` may be unused for certain kinds
+of lookups, and ``q`` is the level-of-detail bias for biased sampling.
+
+These attributes are called "generic" because they may be used for anything
+else, including parameters, texture generation information, or anything that
+can be stored inside a four-component vector.
+
+TGSI_SEMANTIC_NORMAL
+""""""""""""""""""""
+
+XXX no clue.
+
+TGSI_SEMANTIC_FACE
+""""""""""""""""""
+
+FACE is the facing bit, to store the facing information for the fragment
+shader. ``(f, 0, 0, 1)`` is the format. The first component will be positive
+when the fragment is front-facing, and negative when the component is
+back-facing.
+
+TGSI_SEMANTIC_EDGEFLAG
+""""""""""""""""""""""
+
+XXX no clue