3 # Copyright 2009 VMware, Inc.
4 # Copyright 2014 Intel Corporation
7 # Permission is hereby granted, free of charge, to any person obtaining a
8 # copy of this software and associated documentation files (the
9 # "Software"), to deal in the Software without restriction, including
10 # without limitation the rights to use, copy, modify, merge, publish,
11 # distribute, sub license, and/or sell copies of the Software, and to
12 # permit persons to whom the Software is furnished to do so, subject to
13 # the following conditions:
15 # The above copyright notice and this permission notice (including the
16 # next paragraph) shall be included in all copies or substantial portions
19 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
20 # OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
21 # MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
22 # IN NO EVENT SHALL VMWARE AND/OR ITS SUPPLIERS BE LIABLE FOR
23 # ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
24 # TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
25 # SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
43 VERY_LARGE
= 99999999999999999999999
46 """Describes a color channel."""
48 def __init__(self
, type, norm
, size
):
52 self
.sign
= type in (SIGNED
, FLOAT
)
53 self
.name
= None # Set when the channels are added to the format
54 self
.shift
= -1 # Set when the channels are added to the format
55 self
.index
= -1 # Set when the channels are added to the format
64 def __eq__(self
, other
):
65 return self
.type == other
.type and self
.norm
== other
.norm
and self
.size
== other
.size
68 """Returns the maximum representable number."""
69 if self
.type == FLOAT
:
73 if self
.type == UNSIGNED
:
74 return (1 << self
.size
) - 1
75 if self
.type == SIGNED
:
76 return (1 << (self
.size
- 1)) - 1
80 """Returns the minimum representable number."""
81 if self
.type == FLOAT
:
83 if self
.type == UNSIGNED
:
87 if self
.type == SIGNED
:
88 return -(1 << (self
.size
- 1))
92 """Returns the value that represents 1.0f."""
93 if self
.type == UNSIGNED
:
94 return (1 << self
.size
) - 1
95 if self
.type == SIGNED
:
96 return (1 << (self
.size
- 1)) - 1
101 """Returns the datatype corresponding to a channel type and size"""
102 return _get_datatype(self
.type, self
.size
)
105 """Describes a swizzle operation.
107 A Swizzle is a mapping from one set of channels in one format to the
108 channels in another. Each channel in the destination format is
109 associated with one of the following constants:
111 * SWIZZLE_X: The first channel in the source format
112 * SWIZZLE_Y: The second channel in the source format
113 * SWIZZLE_Z: The third channel in the source format
114 * SWIZZLE_W: The fourth channel in the source format
115 * SWIZZLE_ZERO: The numeric constant 0
116 * SWIZZLE_ONE: THe numeric constant 1
117 * SWIZZLE_NONE: No data available for this channel
119 Sometimes a Swizzle is represented by a 4-character string. In this
120 case, the source channels are represented by the characters "x", "y",
121 "z", and "w"; the numeric constants are represented as "0" and "1"; and
122 no mapping is represented by "_". For instance, the map from
123 luminance-alpha to rgba is given by "xxxy" because each of the three rgb
124 channels maps to the first luminance-alpha channel and the alpha channel
125 maps to second luminance-alpha channel. The mapping from bgr to rgba is
126 given by "zyx1" because the first three colors are reversed and alpha is
130 __identity_str
= 'xyzw01_'
140 def __init__(self
, swizzle
):
141 """Creates a Swizzle object from a string or array."""
142 if isinstance(swizzle
, str):
143 swizzle
= [Swizzle
.__identity
_str
.index(c
) for c
in swizzle
]
145 swizzle
= list(swizzle
)
147 assert isinstance(s
, int) and 0 <= s
and s
<= Swizzle
.SWIZZLE_NONE
149 assert len(swizzle
) <= 4
151 self
.__list
= swizzle
+ [Swizzle
.SWIZZLE_NONE
] * (4 - len(swizzle
))
152 assert len(self
.__list
) == 4
155 """Returns an iterator that iterates over this Swizzle.
157 The values that the iterator produces are described by the SWIZZLE_*
160 return self
.__list
.__iter
__()
163 """Returns a string representation of this Swizzle."""
164 return ''.join(Swizzle
.__identity
_str
[i
] for i
in self
.__list
)
166 def __getitem__(self
, idx
):
167 """Returns the SWIZZLE_* constant for the given destination channel.
169 Valid values for the destination channel include any of the SWIZZLE_*
170 constants or any of the following single-character strings: "x", "y",
171 "z", "w", "r", "g", "b", "a", "z" "s".
174 if isinstance(idx
, int):
175 assert idx
>= Swizzle
.SWIZZLE_X
and idx
<= Swizzle
.SWIZZLE_NONE
176 if idx
<= Swizzle
.SWIZZLE_W
:
177 return self
.__list
.__getitem
__(idx
)
180 elif isinstance(idx
, str):
182 idx
= 'xyzw'.find(idx
)
184 idx
= 'rgba'.find(idx
)
189 return self
.__list
.__getitem
__(idx
)
193 def __mul__(self
, other
):
194 """Returns the composition of this Swizzle with another Swizzle.
196 The resulting swizzle is such that, for any valid input to
197 __getitem__, (a * b)[i] = a[b[i]].
199 assert isinstance(other
, Swizzle
)
200 return Swizzle(self
[x
] for x
in other
)
203 """Returns a pseudo-inverse of this swizzle.
205 Since swizzling isn't necisaraly a bijection, a Swizzle can never
206 be truely inverted. However, the swizzle returned is *almost* the
207 inverse of this swizzle in the sense that, for each i in range(3),
208 a[a.inverse()[i]] is either i or SWIZZLE_NONE. If swizzle is just
209 a permutation with no channels added or removed, then this
210 function returns the actual inverse.
212 This "pseudo-inverse" idea can be demonstrated by mapping from
213 luminance-alpha to rgba that is given by "xxxy". To get from rgba
214 to lumanence-alpha, we use Swizzle("xxxy").inverse() or "xw__".
215 This maps the first component in the lumanence-alpha texture is
216 the red component of the rgba image and the second to the alpha
217 component, exactly as you would expect.
219 rev
= [Swizzle
.SWIZZLE_NONE
] * 4
222 if self
.__list
[j
] == i
and rev
[i
] == Swizzle
.SWIZZLE_NONE
:
228 """Describes a pixel format."""
230 def __init__(self
, name
, layout
, block_width
, block_height
, block_depth
, channels
, swizzle
, colorspace
):
231 """Constructs a Format from some metadata and a list of channels.
233 The channel objects must be unique to this Format and should not be
234 re-used to construct another Format. This is because certain channel
235 information such as shift, offset, and the channel name are set when
236 the Format is created and are calculated based on the entire list of
240 name -- Name of the format such as 'MESA_FORMAT_A8R8G8B8'
241 layout -- One of 'array', 'packed' 'other', or a compressed layout
242 block_width -- The block width if the format is compressed, 1 otherwise
243 block_height -- The block height if the format is compressed, 1 otherwise
244 block_depth -- The block depth if the format is compressed, 1 otherwise
245 channels -- A list of Channel objects
246 swizzle -- A Swizzle from this format to rgba
247 colorspace -- one of 'rgb', 'srgb', 'yuv', or 'zs'
251 self
.block_width
= block_width
252 self
.block_height
= block_height
253 self
.block_depth
= block_depth
254 self
.channels
= channels
255 assert isinstance(swizzle
, Swizzle
)
256 self
.swizzle
= swizzle
258 assert colorspace
in (RGB
, SRGB
, YUV
, ZS
)
259 self
.colorspace
= colorspace
263 if self
.colorspace
in (RGB
, SRGB
):
264 for (i
, s
) in enumerate(swizzle
):
266 chan_names
[s
] += 'rgba'[i
]
267 elif colorspace
== ZS
:
268 for (i
, s
) in enumerate(swizzle
):
270 chan_names
[s
] += 'zs'[i
]
272 chan_names
= ['x', 'y', 'z', 'w']
274 for c
, name
in zip(self
.channels
, chan_names
):
275 assert c
.name
is None
285 # Set indices and offsets
286 if self
.layout
== PACKED
:
288 for channel
in self
.channels
:
289 assert channel
.shift
== -1
290 channel
.shift
= shift
291 shift
+= channel
.size
292 for idx
, channel
in enumerate(self
.channels
):
293 assert channel
.index
== -1
296 pass # Shift means nothing here
301 def short_name(self
):
302 """Returns a short name for a format.
304 The short name should be suitable to be used as suffix in function
309 if name
.startswith('MESA_FORMAT_'):
310 name
= name
[len('MESA_FORMAT_'):]
314 def block_size(self
):
315 """Returns the block size (in bits) of the format."""
317 for channel
in self
.channels
:
321 def num_channels(self
):
322 """Returns the number of channels in the format."""
324 for channel
in self
.channels
:
329 def array_element(self
):
330 """Returns a non-void channel if this format is an array, otherwise None.
332 If the returned channel is not None, then this format can be
333 considered to be an array of num_channels() channels identical to the
336 if self
.layout
== ARRAY
:
337 return self
.channels
[0]
338 elif self
.layout
== PACKED
:
339 ref_channel
= self
.channels
[0]
340 if ref_channel
.type == VOID
:
341 ref_channel
= self
.channels
[1]
342 for channel
in self
.channels
:
343 if channel
.size
== 0 or channel
.type == VOID
:
345 if channel
.size
!= ref_channel
.size
or channel
.size
% 8 != 0:
347 if channel
.type != ref_channel
.type:
349 if channel
.norm
!= ref_channel
.norm
:
356 """Returns true if this format can be considered an array format.
358 This function will return true if self.layout == 'array'. However,
359 some formats, such as MESA_FORMAT_A8G8B8R8, can be considered as
360 array formats even though they are technically packed.
362 return self
.array_element() != None
364 def is_compressed(self
):
365 """Returns true if this is a compressed format."""
366 return self
.block_width
!= 1 or self
.block_height
!= 1 or self
.block_depth
!= 1
369 """Returns true if this format is an integer format.
373 if self
.layout
not in (ARRAY
, PACKED
):
375 for channel
in self
.channels
:
376 if channel
.type not in (VOID
, UNSIGNED
, SIGNED
):
381 """Returns true if this format is an floating-point format."""
382 if self
.layout
not in (ARRAY
, PACKED
):
384 for channel
in self
.channels
:
385 if channel
.type not in (VOID
, FLOAT
):
389 def channel_type(self
):
390 """Returns the type of the channels in this format."""
392 for c
in self
.channels
:
397 assert c
.type == _type
400 def channel_size(self
):
401 """Returns the size (in bits) of the channels in this format.
403 This function should only be called if all of the channels have the
404 same size. This is always the case if is_array() returns true.
407 for c
in self
.channels
:
412 assert c
.size
== size
415 def max_channel_size(self
):
416 """Returns the size of the largest channel."""
418 for c
in self
.channels
:
421 size
= max(size
, c
.size
)
424 def is_normalized(self
):
425 """Returns true if this format is normalized.
427 While only integer formats can be normalized, not all integer formats
428 are normalized. Normalized integer formats are those where the
429 integer value is re-interpreted as a fixed point value in the range
433 for c
in self
.channels
:
438 assert c
.norm
== norm
441 def has_channel(self
, name
):
442 """Returns true if this format has the given channel."""
443 if self
.is_compressed():
444 # Compressed formats are a bit tricky because the list of channels
445 # contains a single channel of type void. Since we don't have any
446 # channel information there, we pull it from the swizzle.
447 if str(self
.swizzle
) == 'xxxx':
449 elif str(self
.swizzle
)[0:3] in ('xxx', 'yyy'):
453 return self
.swizzle
['a'] <= Swizzle
.SWIZZLE_W
457 return self
.swizzle
[name
] <= Swizzle
.SWIZZLE_W
461 for channel
in self
.channels
:
462 if channel
.name
== name
:
466 def get_channel(self
, name
):
467 """Returns the channel with the given name if it exists."""
468 for channel
in self
.channels
:
469 if channel
.name
== name
:
474 """Returns the datatype corresponding to a format's channel type and size"""
475 if self
.layout
== PACKED
:
476 if self
.block_size() == 8:
478 if self
.block_size() == 16:
480 if self
.block_size() == 32:
485 return _get_datatype(self
.channel_type(), self
.channel_size())
487 def _get_datatype(type, size
):
495 elif type == UNSIGNED
:
516 def _parse_channels(fields
, layout
, colorspace
, swizzle
):
522 type = field
[0] if field
[0] else 'x'
526 size
= int(field
[2:])
529 size
= int(field
[1:])
531 channel
= Channel(type, norm
, size
)
532 channels
.append(channel
)
537 """Parse a format description in CSV format.
539 This function parses the given CSV file and returns an iterable of
542 with
open(filename
) as stream
:
545 comment
= line
.index('#')
549 line
= line
[:comment
]
554 fields
= [field
.strip() for field
in line
.split(',')]
558 block_width
= int(fields
[2])
559 block_height
= int(fields
[3])
560 block_depth
= int(fields
[4])
561 colorspace
= fields
[10]
564 swizzle
= Swizzle(fields
[9])
566 sys
.exit("error parsing swizzle for format " + name
)
567 channels
= _parse_channels(fields
[5:9], layout
, colorspace
, swizzle
)
569 yield Format(name
, layout
, block_width
, block_height
, block_depth
, channels
, swizzle
, colorspace
)