src/base/pixel.hh

   1 /*
   2  * Copyright (c) 2015 ARM Limited
   3  * All rights reserved
   4  *
   5  * The license below extends only to copyright in the software and shall
   6  * not be construed as granting a license to any other intellectual
   7  * property including but not limited to intellectual property relating
   8  * to a hardware implementation of the functionality of the software
   9  * licensed hereunder.  You may use the software subject to the license
  10  * terms below provided that you ensure that this notice is replicated
  11  * unmodified and in its entirety in all distributions of the software,
  12  * modified or unmodified, in source code or in binary form.
  13  *
  14  * Redistribution and use in source and binary forms, with or without
  15  * modification, are permitted provided that the following conditions are
  16  * met: redistributions of source code must retain the above copyright
  17  * notice, this list of conditions and the following disclaimer;
  18  * redistributions in binary form must reproduce the above copyright
  19  * notice, this list of conditions and the following disclaimer in the
  20  * documentation and/or other materials provided with the distribution;
  21  * neither the name of the copyright holders nor the names of its
  22  * contributors may be used to endorse or promote products derived from
  23  * this software without specific prior written permission.
  24  *
  25  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  26  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  27  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  28  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  29  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  30  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  31  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  32  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  33  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  34  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  35  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  36  *
  37  * Authors: Andreas Sandberg
  38  */
  39
  40 #ifndef __BASE_PIXEL_HH__
  41 #define __BASE_PIXEL_HH__
  42
  43 #include <cmath>
  44 #include <cstdint>
  45 #include <string>
  46 #include <vector>
  47
  48 #include "base/compiler.hh"
  49 #include "base/cprintf.hh"
  50 #include "base/str.hh"
  51 #include "base/types.hh"
  52
  53 /**
  54  * Internal gem5 representation of a Pixel.
  55  */
  56 struct Pixel
  57 {
  58     Pixel()
  59         : red(0), green(0), blue(0), padding(0) {}
  60
  61     Pixel(uint8_t _red, uint8_t _green, uint8_t _blue)
  62         : red(_red), green(_green), blue(_blue), padding(0) {}
  63
  64     uint8_t red;
  65     uint8_t green;
  66     uint8_t blue;
  67     uint8_t padding;
  68 };
  69
  70 inline bool
  71 operator==(const Pixel &lhs, const Pixel &rhs)
  72 {
  73     return lhs.red == rhs.red &&
  74         lhs.green == rhs.green &&
  75         lhs.blue == rhs.blue &&
  76         lhs.padding == rhs.padding;
  77 }
  78
  79 /**
  80  * Configurable RGB pixel converter.
  81  *
  82  * This class converts between external RGB representations and gem5's
  83  * internal Pixel representation. The class assumes that pixels are
  84  * stored in a word of configurable length (up to 32 bits). Individual
  85  * pixels are assumed to be represented by contiguous bit ranges in
  86  * the word (i.e., it is possible to shift and mask out a contiguous
  87  * bit range for each pixel).
  88  */
  89 class PixelConverter
  90 {
  91   public:
  92     /**
  93      * Color channel conversion and scaling helper class.
  94      */
  95     struct Channel {
  96         /**
  97          * @param offset Offset in bits.
  98          * @param width Width in bits.
  99          */
 100         Channel(unsigned offset, unsigned width);
 101
 102         /**
 103          * Get the value of a single color channel represented as an
 104          * 8-bit number.
 105          */
 106         uint8_t toPixel(uint32_t word) const {
 107             return round(((word >> offset) & mask) * factor);
 108         }
 109
 110         /**
 111          * Convert an 8-bit representation of a color into an external
 112          * format.
 113          */
 114         uint32_t fromPixel(uint8_t ch) const {
 115             return (static_cast<uint8_t>(round(ch / factor)) & mask) << offset;
 116         }
 117
 118         /** Offset in bits */
 119         unsigned offset;
 120         /** Bit mask (after shifting) */
 121         unsigned mask;
 122         /**
 123          * Scaling factor when converting to the full range of an
 124          * 8-bit color channel
 125          */
 126         float factor;
 127     };
 128
 129     PixelConverter(unsigned length,
 130                    unsigned ro, unsigned go, unsigned bo,
 131                    unsigned rw, unsigned gw, unsigned bw,
 132                    ByteOrder byte_order = LittleEndianByteOrder);
 133
 134     /** Get the Pixel representation of a color word. */
 135     Pixel toPixel(uint32_t word) const {
 136         return Pixel(ch_r.toPixel(word),
 137                      ch_g.toPixel(word),
 138                      ch_b.toPixel(word));
 139     }
 140
 141     /** Get a Pixel representation by reading a word from memory. */
 142     Pixel toPixel(const uint8_t *rfb) const {
 143         return toPixel(readWord(rfb));
 144     }
 145
 146     /** Convert a Pixel into a color word */
 147     uint32_t fromPixel(const Pixel &pixel) const {
 148         return ch_r.fromPixel(pixel.red) |
 149             ch_g.fromPixel(pixel.green) |
 150             ch_b.fromPixel(pixel.blue);
 151     }
 152
 153     /**
 154      * Convert a pixel into a color word and store the resulting word
 155      * in memory.
 156      */
 157     void fromPixel(uint8_t *rfb, const Pixel &pixel) const {
 158         writeWord(rfb, fromPixel(pixel));
 159     }
 160
 161     /**
 162      * Read a word of a given length and endianness from memory.
 163      *
 164      * The number of bytes read from memory is determined by the
 165      * length of a color word. Note that some of the bytes may be
 166      * padding.
 167      *
 168      * @param p Pointer to the first byte in the word.
 169      * @return Word in host endianness.
 170      */
 171     uint32_t readWord(const uint8_t *p) const;
 172     /**
 173      * Write a word of a given length and endianness to memory.
 174      *
 175      * @param p Pointer to the first byte in memory.
 176      * @param word Word to store (host endianness).
 177      */
 178     void writeWord(uint8_t *p, uint32_t word) const;
 179
 180     /** Bytes per pixel when stored in memory (including padding) */
 181     unsigned length;
 182     /**
 183      * Number of bits used to represent one pixel value (excluding
 184      * padding). This could be less than length * 8 if the pixel value
 185      * is padded.
 186      */
 187     unsigned depth;
 188     /** Byte order when stored to memory. */
 189     ByteOrder byte_order;
 190
 191     /** Red channel conversion helper */
 192     Channel ch_r;
 193     /** Green channel conversion helper */
 194     Channel ch_g;
 195     /** Blue channel conversion helper */
 196     Channel ch_b;
 197
 198     /** Predefined 32-bit RGB (red in least significant bits, 8
 199      * bits/channel, little endian) conversion helper */
 200     static const PixelConverter rgba8888_le;
 201     /** Predefined 16-bit RGB565 (red in least significant bits,
 202      * little endian) conversion helper */
 203     static const PixelConverter rgb565_le;
 204
 205     /** Predefined 32-bit RGB (red in least significant bits, 8
 206      * bits/channel, big endian) conversion helper */
 207     static const PixelConverter rgba8888_be;
 208     /** Predefined 16-bit RGB565 (red in least significant bits,
 209      * big endian) conversion helper */
 210     static const PixelConverter rgb565_be;
 211 };
 212
 213 inline bool
 214 to_number(const std::string &value, Pixel &retval)
 215 {
 216     uint32_t num;
 217     if (!to_number(value, num))
 218         return false;
 219
 220     retval = PixelConverter::rgba8888_le.toPixel(num);
 221     return true;
 222 }
 223
 224 inline std::ostream &
 225 operator<<(std::ostream &os, const Pixel &pxl)
 226 {
 227     os << csprintf("%#.08x", PixelConverter::rgba8888_le.fromPixel(pxl));
 228     return os;
 229 }
 230
 231 #endif // __BASE_PIXEL_HH__