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

[Brian Paul]

On 06/12/2017 01:38 PM, Dieter Nützel wrote:
> 'Undefined' or/equal as 'don't care'
> which is much more useful for 'tricks'
> like 'we' learned in chip design clause 3 decades ago?
>
> But GL didn't allow 'don't care' I think?

gl_SampleID, for example, is a 1-component int in GLSL so the other 
three components are irrelevant.  Similar story for the rest.

-Brian


> Sorry, that I step in...;-)
>
> Dieter
>
>
> Am 12.06.2017 21:22, schrieb Ilia Mirkin:
>> That's actually stronger than saying that you'll leave them alone...
>> and probably better. Undefined sounds great to me!
>>
>> On Mon, Jun 12, 2017 at 3:13 PM, Brian Paul <brianp at vmware.com> wrote:
>>> Or say they're undefined: sample pos = (x, y, undef, undef), for
>>> example.
>>>
>>> I'd be OK with that.  You?
>>>
>>> -Brian
>>>
>>>
>>> On 06/12/2017 11:47 AM, Ilia Mirkin wrote:
>>>>
>>>> Perhaps this is wrong in the grand scheme of things, but at least
>>>> nouveau will *only* set the defined components of dst, not the
>>>> undefined ones. Perhaps we should zero those out?
>>>>
>>>> On Mon, Jun 12, 2017 at 1:37 PM, Brian Paul <brianp at vmware.com> 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).
>>>>>
>>>>>   .. 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
>>>>>   """"""""""""""""""""""""
>>>>> --
>>>>> 1.9.1
>>>>>
>>>>> _______________________________________________
>>>>> mesa-dev mailing list
>>>>> mesa-dev at lists.freedesktop.org
>>>>>
>>>>> https://urldefense.proofpoint.com/v2/url?u=https-3A__lists.freedesktop.org_mailman_listinfo_mesa-2Ddev&d=DwIBaQ&c=uilaK90D4TOVoH58JNXRgQ&r=Ie7_encNUsqxbSRbqbNgofw0ITcfE8JKfaUjIQhncGA&m=Rf5WxNSp1rJlF8Sn19utEreOUJk2L1hqNZSDk3yPLFc&s=44Rk8znw2BUsD4CJtTuGgIp-i6eBDQbhywzt8Ctox5c&e=
>>>>>
>>>
>>>
>> _______________________________________________
>> mesa-dev mailing list
>> mesa-dev at lists.freedesktop.org
>> https://urldefense.proofpoint.com/v2/url?u=https-3A__lists.freedesktop.org_mailman_listinfo_mesa-2Ddev&d=DwICAg&c=uilaK90D4TOVoH58JNXRgQ&r=Ie7_encNUsqxbSRbqbNgofw0ITcfE8JKfaUjIQhncGA&m=WOmTsSuyvjDJl0PNdiOuY2svuryEQuUAFiubB6XRx8Y&s=qHAM2JjS3FydByeaOXVbye2gaaT9HVF9m3_h6gq1wvY&e=
>