Line data    Source code

       1           0 : /*
       2             : 
       3             : OOPixMap.h
       4             : 
       5             : Types for low-level pixel map manipulation.
       6             : 
       7             : 
       8             : Copyright (C) 2010-2013 Jens Ayton
       9             : 
      10             : Permission is hereby granted, free of charge, to any person obtaining a copy
      11             : of this software and associated documentation files (the "Software"), to deal
      12             : in the Software without restriction, including without limitation the rights
      13             : to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
      14             : copies of the Software, and to permit persons to whom the Software is
      15             : furnished to do so, subject to the following conditions:
      16             : 
      17             : The above copyright notice and this permission notice shall be included in all
      18             : copies or substantial portions of the Software.
      19             : 
      20             : THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
      21             : IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
      22             : FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
      23             : AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
      24             : LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
      25             : OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
      26             : SOFTWARE.
      27             : 
      28             : */
      29             : 
      30             : #import "OOMaths.h"
      31             : 
      32             : 
      33           0 : typedef uint_fast32_t           OOPixMapDimension;              // Note: dimensions are assumed to be less than 1048576 (2^20) pixels.
      34             : 
      35           0 : #define OORoundUpToPowerOf2_PixMap OORoundUpToPowerOf2_32
      36             : 
      37             : 
      38           0 : typedef enum
      39             : {
      40             :         kOOPixMapInvalidFormat          = 0,
      41             :         kOOPixMapGrayscale                      = 1,
      42             :         kOOPixMapGrayscaleAlpha         = 2,
      43             :         kOOPixMapRGBA                           = 4
      44             : } OOPixMapFormat;
      45             : 
      46             : 
      47           0 : typedef struct OOPixMap
      48             : {
      49           0 :         void                                    *pixels;
      50           0 :         OOPixMapDimension               width, height;
      51           0 :         OOPixMapFormat                  format;
      52           0 :         size_t                                  rowBytes;
      53           0 :         size_t                                  bufferSize;
      54           0 : } OOPixMap;
      55             : 
      56             : 
      57           0 : extern const OOPixMap kOONullPixMap;
      58             : 
      59             : 
      60           0 : OOINLINE BOOL OOIsNullPixMap(OOPixMap pixMap)  { return pixMap.pixels == NULL; }
      61           0 : BOOL OOIsValidPixMap(OOPixMap pixMap);
      62           0 : OOINLINE size_t OOMinimumPixMapBufferSize(OOPixMap pixMap)  { return pixMap.rowBytes * pixMap.height; }
      63             : 
      64             : 
      65             : /*      OOMakePixMap()
      66             :         Stuff an OOPixMap struct. Returns kOONullPixMap if the result would be
      67             :         invalid. If rowBytes or bufferSize are zero, minimum valid values will be
      68             :         used.
      69             : */
      70           0 : OOPixMap OOMakePixMap(void *pixels, OOPixMapDimension width, OOPixMapDimension height, OOPixMapFormat format, size_t rowBytes, size_t bufferSize);
      71             : 
      72             : /*      OOAllocatePixMap()
      73             :         Create an OOPixMap, allocating storage. If rowBytes or bufferSize are zero,
      74             :         minimum valid values will be used.
      75             : */
      76           0 : OOPixMap OOAllocatePixMap(OOPixMapDimension width, OOPixMapDimension height, OOPixMapFormat format, size_t rowBytes, size_t bufferSize);
      77             : 
      78             : 
      79             : /*      OOFreePixMap()
      80             :         Deallocate a pixmap's buffer (with free()), and clear out the struct.
      81             : */
      82           0 : void OOFreePixMap(OOPixMap *ioPixMap);
      83             : 
      84             : 
      85             : /*      OODuplicatePixMap()
      86             :         Create a pixmap with the same pixel contents as a source pixmap, and
      87             :         optional padding. If desiredSize is less than the required space for the
      88             :         pixmap, it will be ignored. The contents of padding bytes are unspecified.
      89             : */
      90           0 : OOPixMap OODuplicatePixMap(OOPixMap srcPixMap, size_t desiredSize);
      91             : 
      92             : 
      93             : /*      OOResizePixMap()
      94             :         Set the size of a pixmap's buffer. Fails if specified size is smaller than
      95             :         required to fit the current pixels.
      96             : */
      97           0 : BOOL OOResizePixMap(OOPixMap *ioPixMap, size_t desiredSize);
      98             : 
      99             : 
     100             : /*      OOCompactPixMap()
     101             :         Remove any trailing space in a pixmap's buffer, if possible.
     102             : */
     103           0 : OOINLINE void OOCompactPixMap(OOPixMap *ioPixMap)  { OOResizePixMap(ioPixMap, OOMinimumPixMapBufferSize(*ioPixMap)); }
     104             : 
     105             : 
     106             : /*      OOExpandPixMap()
     107             :         Expand pixmap to at least desiredSize bytes. Returns false on failure.
     108             : */
     109           0 : BOOL OOExpandPixMap(OOPixMap *ioPixMap, size_t desiredSize);
     110             : 
     111             : 
     112             : #ifndef NDEBUG
     113           0 : void OODumpPixMap(OOPixMap pixMap, NSString *name);
     114             : #else
     115             : #define OODumpPixMap(p, n)  do {} while (0)
     116             : #endif
     117             : 
     118             : 
     119           0 : BOOL OOIsValidPixMapFormat(OOPixMapFormat format);
     120             : 
     121             : 
     122             : #ifndef NDEBUG
     123           0 : unsigned short OOPixMapBytesPerPixelForFormat(OOPixMapFormat format) PURE_FUNC;
     124             : #else
     125             : OOINLINE unsigned short OOPixMapBytesPerPixelForFormat(OOPixMapFormat format)
     126             : {
     127             :         // Currently, format values are component counts. This is subject to change.
     128             :         return format;
     129             : }
     130             : #endif
     131             : 
     132           0 : OOINLINE unsigned short OOPixMapBytesPerPixel(OOPixMap pixMap)
     133             : {
     134             :         return OOPixMapBytesPerPixelForFormat(pixMap.format);
     135             : }
     136             : 
     137           0 : NSString *OOPixMapFormatName(OOPixMapFormat format) PURE_FUNC;
     138             : 
     139           0 : BOOL OOPixMapFormatHasAlpha(OOPixMapFormat format) PURE_FUNC;