[Mesa-dev] [PATCH 1/2] gallium/docs: improve docs for SAMPLE_POS, SAMPLE_INFO, TXQS, MSAA semantics

[Roland Scheidegger]

Am 12.06.2017 um 21:19 schrieb Brian Paul:
> On 06/12/2017 11:50 AM, Nicolai Hähnle wrote:
>> On 12.06.2017 19:37, Brian Paul wrote:
>>> For the SAMPLE_POS and SAMPLE_INFO opcodes, clarify resource vs. render
>>> target queries, range of postion values, swizzling, etc.  We basically
>>> follow the DX10.1 conventions.
>>>
>>> For the TXQS opcode and TGSI_SEMANTIC_SAMPLEID, clarify return value
>>> and type.
>>>
>>> For the TGSI_SEMANTIC_SAMPLEPOS system value, clarify the range of
>>> positions returned.
>>> ---
>>>   src/gallium/docs/source/tgsi.rst | 53
>>> +++++++++++++++++++++++++++++++---------
>>>   1 file changed, 42 insertions(+), 11 deletions(-)
>>>
>>> diff --git a/src/gallium/docs/source/tgsi.rst
>>> b/src/gallium/docs/source/tgsi.rst
>>> index 7fb963f..310b49d 100644
>>> --- a/src/gallium/docs/source/tgsi.rst
>>> +++ b/src/gallium/docs/source/tgsi.rst
>>> @@ -982,7 +982,9 @@ XXX doesn't look like most of the opcodes really
>>> belong here.
>>>   .. opcode:: TXQS - Texture Samples Query
>>>     This retrieves the number of samples in the texture, and stores it
>>> -  into the x component. The other components are undefined.
>>> +  into the x component as an unsigned integer. The other components are
>>> +  undefined.  If the texture is not multisampled, this function returns
>>> +  (1, 0, 0, 0).
>>>   .. math::
>>> @@ -2538,14 +2540,40 @@ after lookup.
>>>   .. opcode:: SAMPLE_POS
>>> -  Query the position of a given sample.  dst receives float4 (x, y,
>>> 0, 0)
>>> -  indicated where the sample is located. If the resource is not a
>>> multi-sample
>>> -  resource and not a render target, the result is 0.
>>> +  Query the position of a sample in the given resource or render target
>>> +  when per-sample fragment shading is in effect.
>>> +
>>> +  Syntax: ``SAMPLE_POS dst, source, sample_index``
>>> +
>>> +  dst receives float4 (x, y, 0, 0) indicated where the sample is
>>> located.
>>> +  Sample locations are in the range [0, 1] where 0.5 is the center of
>>> the
>>> +  fragment.
>>> +
>>> +  source is either a sampler view (to indicate a shader resource) or
>>> temp
>>> +  register (to indicate the render target).  The source register may
>>> have
>>> +  an optional swizzle to apply to the returned result
>>> +
>>> +  sample_index is an integer scalar indicating which sample position
>>> is to
>>> +  be queried.
>>> +
>>> +  If per-sample shading is not in effect or the source resource or
>>> render
>>> +  target is not multisampled, the result is (0, 0, 0, 0).
>>
>> We don't actually implement SAMPLE_POS in radeonsi, but are you sure
>> this is a good idea? Wouldn't it make more sense that the result is
>> (0.5, 0.5, 0, 0)?
> 
> I think you're right.  The DX docs say the default (in some cases) is
> zeros, which would correspond the fragment center.  So that'd be (0.5,
> 0.5, 0, 0) for GL (which is what the extension spec indicates).

I'd argue you strictly can't use these opcodes with GL (but they are
probably not specified correctly for dx10 neither right now).
I'm not sure which extension you're talking about, but generally for all
gallium sample opcodes they won't work in gl in any case because you
need opcodes taking samplers, not sampler views (we're going to also
need a dx10 lod opcode version for that reason.)
(And yes, d3d10.1 specifies the value in there is relative to pixel
center, hence 0).

Albeit those opcodes working both for rasterizer and resources is still
weird...

Roland


> I'll post updated patches...
> 
> -Brian
> 
>>
>> The rest look good to me.
>>
>> Cheers,
>> Nicolai
>>
>>
>>>   .. opcode:: SAMPLE_INFO
>>> -  dst receives number of samples in x.  If the resource is not a
>>> multi-sample
>>> -  resource and not a render target, the result is 0.
>>> +  Query the number of samples in a multisampled resource or render
>>> target.
>>> +
>>> +  Syntax: ``SAMPLE_INFO dst, source``
>>> +
>>> +  dst receives int4 (n, 0, 0, 0) where n is the number of samples in a
>>> +  resource or the render target.
>>> +
>>> +  source is either a sampler view (to indicate a shader resource) or
>>> temp
>>> +  register (to indicate the render target).  The source register may
>>> have
>>> +  an optional swizzle to apply to the returned result
>>> +
>>> +  If per-sample shading is not in effect or the source resource or
>>> render
>>> +  target is not multisampled, the result is (1, 0, 0, 0).
>>>   .. _resourceopcodes:
>>> @@ -3284,15 +3312,18 @@ TGSI_SEMANTIC_SAMPLEID
>>>   """"""""""""""""""""""
>>>   For fragment shaders, this semantic label indicates that a system
>>> value
>>> -contains the current sample id (i.e. gl_SampleID).
>>> -This is an integer value, and only the X component is used.
>>> +contains the current sample id (i.e. gl_SampleID) as an unsigned int.
>>> +Only the X component is used.  If per-sample shading is not enabled,
>>> +the result is (0, 0, 0, 0).
>>>   TGSI_SEMANTIC_SAMPLEPOS
>>>   """""""""""""""""""""""
>>> -For fragment shaders, this semantic label indicates that a system value
>>> -contains the current sample's position (i.e. gl_SamplePosition). Only
>>> the X
>>> -and Y values are used.
>>> +For fragment shaders, this semantic label indicates that a system
>>> +value contains the current sample's position as float4(x, y, 0, 0) in
>>> +the render target (i.e.  gl_SamplePosition) when per-fragment shading
>>> +is in effect.  Position values are in the range [0, 1] where 0.5 is
>>> +the center of the fragment.
>>>   TGSI_SEMANTIC_SAMPLEMASK
>>>   """"""""""""""""""""""""
>>>
>>
>>