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

Mon Jun 12 19:38:31 UTC 2017

'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?
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://lists.freedesktop.org/mailman/listinfo/mesa-dev