GL Studio Safety Critical Embedded C++ Runtime Library
gls_image.h
Go to the documentation of this file.
1 #ifndef _GLS_IMAGE_H
2 #define _GLS_IMAGE_H
3 
4 /*! \file gls_image.h
5 
6 \brief This header defines the GlsImage class which encapsulates textures
7  in the GL Studio DO-178B Runtime Library.
8 
9 \par Copyright Information
10 Copyright (C) 1999-2012 The DiSTI Corporation<br>
11 Orlando, FL USA<br>
12 All rights reserved.<br>
13 
14  This file is copyrighted software and contains proprietary trade secrets of
15 DiSTI, and embodies substantial creative efforts as well as confidential
16 information, ideas, and expressions.
17 
18  Permission to use, and copy this software and its documentation for any
19 purpose is hereby granted per the Distribution Agreement and/or the Licensing
20 Agreement signed with DiSTI. This permission is granted provided that:
21  1. The above copyright notice appears in all copies.
22  2. That both the copyright notice and this permission notice appear in
23  the supporting documentation.
24  3. That the names DiSTI and GL Studio not be used in advertising or
25  publicity pertaining to distribution of the software without specific,
26  written prior permission of DiSTI.
27 
28  Permission to modify the software is granted, but not the right to
29 distribute the source code whether modified, or non-modified. Modifying the
30 software might invalidate the DO-178B certification package.
31 
32  Permission to distribute binaries produced by compiling source code, or
33 modified source code is granted, provided you:
34  1. Provide your name and address as the primary contact for the support
35  of your modified version.
36  2. Retain our contact information in regard to use of the base software.
37 
38  DiSTI does not provide warranty for this software or guarantee that it
39 satisfies any specification or requirement unless otherwise stated in a
40 specific contractual arrangement between the customer and DiSTI.
41 
42 */
43 
44 #include "gls_include.h"
45 #include "gls_state_manager.h"
46 #include "gls_pointer_array.h"
47 #include "gls_class_invariant.h"
48 
49 /** Encapsulates a 2D image
50  * \invariant INVALID_TEXTURE_HANDLE != _textureHandle,
51  * GlsImageInputPixelFormatIsValid( _inputPixelFormat ),
52  * _pixelSize > 0,
53  * ( _height > 0 ) && IsPowerOf2( _height ),
54  * ( _width > 0 ) && IsPowerOf2( _width ),
55  * _imageList != GLS_NULL
56  * ( ( _maxImageWidth > 0u ) && IsPowerOf2( _maxImageWidth ) ),
57  * GlsAssert( GLS_NULL != _scanlineImageData != GLS_NULL
58  */
59 class GlsImage
60 {
61 public:
63 
64  /** enumeration of possible image compression codecs */
66  {
67  IMAGE_CODEC_RAW, /**< Image data is not compressed */
68  IMAGE_CODEC_RLE, /**< Image data is compressed with RLE ( Run Length Encoded ) */
69 
70  #if defined( GLS_DEBUG )
71  IMAGE_CODEC_INVALID /**< Invalid image codec ( GLS_DEBUG only ) */
72  #endif
73  };
74 
75  /** enumeration of supported input pixel formats */
77  {
78  INPUT_PIXEL_FORMAT_RGB, /**< red, green, blue */
79  INPUT_PIXEL_FORMAT_RGBA, /**< red, green, blue, alpha */
80  INPUT_PIXEL_FORMAT_ALPHA, /**< alpha */
81 
82  #if defined( GLS_DEBUG )
83  INPUT_PIXEL_FORMAT_INVALID /**< invalid pixel format ( GLS_DEBUG only ) */
84  #endif
85  };
86 
87  /** This structure is generated and contains information needed to
88  * reconstruct an inline generated image.
89  */
90  struct InlineImage
91  {
92  const GlsUInt32 width; /**< Width of image in pixels. Must be a power of 2 */
93  const GlsUInt32 height; /**< Height of image in pixels. Must be a power of 2 */
94  const InputPixelFormat inputPixelFormat; /**< Input Pixel format of image */
95  const ImageCodec codec; /**< CODEC used to compress image */
96  const GlsUInt32 crc; /**< CRC of uncompressed image data */
97  const GlsUInt32 imageDataSize; /**< Size of data (compressed) */
98  const GlsUInt32 lineLength; /**< Length of each line of inline data, in bytes */
99  const GlsUChar* const *imageData; /**< inline image data */
100 
101  #if defined( GLS_DEBUG )
102  /** Determine if the inline image structure is valid
103  * \return GLS_TRUE if valid else GLS_FALSE
104  * \pre none
105  * \post none
106  */
107  GlsBool IsValid( void ) const;
108  #endif // GLS_DEBUG
109  };
110 
111  /** initialization parameters for GlsImage subsystem */
113  {
114  const GlsUInt32 maxNumImages; /**< maximum number of unique images to support in the image list */
115  const GlsUInt32 maxImageWidth; /**< maximum width in pixels of an image to support (>0, power of 2)*/
116 
117  #if defined( GLS_DEBUG )
118  /** Determine if the initialization parameters are valid ( GLS_DEBUG only )
119  * \return GLS_TRUE if valid else GLS_FALSE
120  * \pre none
121  * \post none
122  */
123  GlsBool IsValid( void ) const;
124  #endif // GLS_DEBUG
125  };
126 
127  /** Initialize the GlsImage subsystem. This is a one time call that must be
128  * made before the image subsystem can be used.
129  * \param initParameters initialization parameters for GlsImage subsystem
130  * \pre GlsImage subsystem has not already been initialized, initParameters.IsValid()
131  * \post GlsImage subsystem intermediate image buffers and image list are allocated
132  */
133  static void Initialize( const InitParameters &initParameters );
134 
135  /** Get an Image object with the given GlsInlineImage data.
136  * If checkForDuplicate is GLS_TRUE, this method checks
137  * to see if an image has already been constructed for the
138  * GlsInlineImage and if found, returns the previously
139  * constructed image.
140  * \param inlineImage GlsInlineImage in question
141  * \param checkForDuplicate GLS_TRUE to check if this inline image is a
142  * duplicate of an existing image else GLS_FALSE
143  * \return image corresponding to given inline image
144  * \pre inlineImage.IsValid(), a GlsStateManager instance does not yet exist,
145  * the GlsImage subsytem has been initialized,
146  * inlineImage.width <= _maxImageWidth
147  * \post new image constructed as needed
148  */
149  static GlsImage* GetGlsImageFromInlineImage( const InlineImage &inlineImage, const GlsBool checkForDuplicate );
150 
151  /** Make this image the active GL texture.
152  * \pre glIsTexture( _textureHandle ) == GL_TRUE
153  * \post image is bound to GL
154  */
155  void BindTexture( GlsStateManager &gl ) const;
156 
157  /** Determine if this image matches the given inline image
158  * \param inlineImage inline image in question
159  * \return GLS_TRUE if matches inline image else GLS_FALSE
160  * \pre inlineImage.IsValid()
161  * \post none
162  */
163  GlsBool IsEqual( const InlineImage &inlineImage ) const;
164 
165 protected:
166  /** This class implements a list of image pointers used for maintaining
167  * a list of images that have been instantiated. This list is used when checking
168  * for duplicate images
169  * \invariant _images invariant holds,
170  * _numImages <= _images.GetSize(),
171  * invariant holds for all images in the list
172  */
173  class ImageList
174  {
175  public:
177 
178  /** Constructor - create an empty image list
179  * \param maxNumImages maximum number of image pointers to hold in list
180  * \pre none
181  * \post instance created, image list is empty
182  */
183  ImageList( const GlsUInt32 maxNumImages );
184 
185  /** Add an image to the image list
186  * \param image image to add
187  * \pre image != GLS_NULL, image is not already in the list, image list
188  * has room for one more image
189  * \post image is added to the list
190  */
191  void AddImage( GlsImage* const image );
192 
193  /** Find an image in the list that corresponds to the given inline image
194  * \param inlineImage inline image in question
195  * \return pointer to corresponding image else GLS_NULL if not in list
196  * \pre inlineImage.IsValid()
197  * \post none
198  */
199  GlsImage* FindImageFromInlineImage( const InlineImage &inlineImage ) const;
200 
201  protected:
202  GlsUInt32 _numImages; /**< number of images added to _images array */
203  GlsPointerArray _images; /**< array of image pointers */
204 
205  #if defined( GLS_DEBUG )
206  /** Find the given image pointer in the image list ( GLS_DEBUG only )
207  * \param image image pointer in question
208  * \return GLS_TRUE if found else GLS_FALSE
209  * \pre image != GLS_NULL
210  * \post none
211  */
212  GlsBool FindImagePointer( const GlsImage* const image ) const;
213  #endif // GLS_DEBUG
214 
215  /** Destructor - shall never be called
216  * \pre none
217  * \post none
218  */
219  virtual ~ImageList();
220 
221  private:
222  // Disable implicit generated Members
223  ImageList& operator=( const ImageList &rhs );
224  ImageList( const ImageList &src );
225  };
226 
227  /** value indicating invalid texture handle */
228  static const GLuint INVALID_TEXTURE_HANDLE = 0u;
229 
230  /** corresponds to layout of a GL_RGBA8 pixel */
231  enum
232  {
233  PIXEL_GL_RED_COMPONENT = 0u, /**< GL_RGBA8 - red component */
234  PIXEL_GL_GREEN_COMPONENT, /**< GL_RGBA8 - green component */
235  PIXEL_GL_BLUE_COMPONENT, /**< GL_RGBA8 - blue component */
236  PIXEL_GL_ALPHA_COMPONENT, /**< GL_RGBA8 - alpha component */
237  NUM_BYTES_PER_PIXEL_GL /**< number of bytes per pixel in GL texture data */
238  };
239 
240  /** number of bytes per input pixel for INPUT_PIXEL_FORMAT_RGB */
242  /** number of bytes per input pixel for INPUT_PIXEL_FORMAT_RGBA */
244  /** number of bytes per input pixel for INPUT_PIXEL_FORMAT_ALPHA */
246 
247  GLuint _textureHandle; /**< The texture handle of the image, else INVALID_TEXTURE_HANDLE */
248  const InputPixelFormat _inputPixelFormat; /**< Input pixel format of image */
249  const GlsUInt32 _width; /**< width of image in pixels. must be a power of 2 */
250  const GlsUInt32 _height; /**< height of image in pixels. must be a power of 2 */
251  const GlsUInt32 _crcValue; /**< CRC value used to determine if two images are the same */
252 
253  static ImageList *_imageList; /**< singleton image list */
254  static GlsUChar *_scanlineImageData; /**< intermediate image buffer for RGBA image data
255  * scanline, number of bytes =
256  * ( NUM_BYTES_PER_PIXEL_GL * _maxWidth */
257 
258  #if defined( GLS_DEBUG )
259  static GlsUInt32 _maxImageWidth; /**< maximum allowed texture width ( GLS_DEBUG only )*/
260  #endif // GLS_DEBUG
261 
262  /** Constructor - create an image from the given inline image
263  * \param inlineImage inline image in question
264  * \pre inlineImage.IsValid(), the GlsImage subsystem has been initialized,
265  * inlineImage.width <= _maxImageWidth
266  * \post image constructed
267  */
268  GlsImage( const InlineImage &inlineImage );
269 
270  /** decode the given inline image and upload to GL
271  * \param inlineImage inline image in question
272  * \pre inlineImage.IsValid(), inlineImage.codec is either IMAGE_CODEC_RLE or IMAGE_CODEC_RAW,
273  * inlineImage.width <= _maxImageWidth,
274  * inlineImage.inputPixelFormat must be either
275  * INPUT_PIXEL_FORMAT_ALPHA, INPUT_PIXEL_FORMAT_RGB, or INPUT_PIXEL_FORMAT_RGBA
276  * empty texture of appropriate size is created and bound to GL,
277  * the GlsImage subsystem has been initialized
278  * \post image is decoded and uploaded to GL
279  */
280  void DecodeImage( const InlineImage &inlineImage );
281 
282  /** Get the number of bytes required per pixel for the given format
283  * \param inputPixelFormat format in question
284  * \return number of bytes required per pixel for format
285  * \pre GlsImageInputPixelFormatIsValid( inputPixelFormat )
286  * \post none
287  */
289 
290  /** Destructor - shall never be called
291  * \pre none
292  * \post none
293  */
294  virtual ~GlsImage();
295 
296 private:
297  // Disable implicit generated Members
298  GlsImage& operator=( const GlsImage &rhs );
299  GlsImage( const GlsImage &src );
300 };
301 
302 #if defined( GLS_DEBUG )
303 #pragma BullseyeCoverage save off
304 /** Determine if the given image codec is valid ( GLS_DEBUG only )
305  * \param imageCodec image codec in question
306  * \return GLS_TRUE if valid else GLS_FALSE
307  * \pre none
308  * \post none
309  */
310 inline GlsBool GlsImageCodecIsValid( const GlsImage::ImageCodec imageCodec )
311 {
312  return( ( GlsImage::IMAGE_CODEC_RAW == imageCodec ) ||
313  ( GlsImage::IMAGE_CODEC_RLE == imageCodec ) );
314 }
315 #pragma BullseyeCoverage restore
316 #endif // GLS_DEBUG
317 
318 #if defined( GLS_DEBUG )
319 #pragma BullseyeCoverage save off
320 /** Determine if the given input pixel format is valid ( GLS_DEBUG only )
321  * \param imageCodec image codec in question
322  * \return GLS_TRUE if valid else GLS_FALSE
323  * \pre none
324  * \post none
325  */
326 inline GlsBool GlsImageInputPixelFormatIsValid( const GlsImage::InputPixelFormat inputPixelFormat )
327 {
328  return( ( GlsImage::INPUT_PIXEL_FORMAT_RGB == inputPixelFormat ) ||
329  ( GlsImage::INPUT_PIXEL_FORMAT_RGBA == inputPixelFormat ) ||
330  ( GlsImage::INPUT_PIXEL_FORMAT_ALPHA == inputPixelFormat ) );
331 }
332 #pragma BullseyeCoverage restore
333 #endif // GLS_DEBUG
334 
335 #endif // _GLS_IMAGE_H
void BindTexture(GlsStateManager &gl) const
static GlsUChar * _scanlineImageData
Definition: gls_image.h:254
InputPixelFormat
Definition: gls_image.h:76
virtual ~GlsImage()
unsigned char GlsUChar
Definition: gls_types.h:61
const GlsUInt32 crc
Definition: gls_image.h:96
This header defines GlsPointerArray which encapsulates an array of pointers in the GL Studio DO-178B ...
Definition: gls_image.h:78
static const GlsUInt32 NUM_BYTES_PER_INPUT_PIXEL_FORMAT_RGBA
Definition: gls_image.h:243
bool GlsBool
Definition: gls_types.h:96
Definition: gls_image.h:80
const GlsUInt32 _height
Definition: gls_image.h:250
#define GLS_CLASS_INVARIANT_DECLARATION(ClassName)
Definition: gls_class_invariant.h:80
Definition: gls_state_manager.h:63
void AddImage(GlsImage *const image)
Definition: gls_image.h:236
const GlsUInt32 _crcValue
Definition: gls_image.h:251
Definition: gls_pointer_array.h:51
Definition: gls_image.h:79
static void Initialize(const InitParameters &initParameters)
const GlsUInt32 maxNumImages
Definition: gls_image.h:114
Definition: gls_image.h:237
static GlsImage * GetGlsImageFromInlineImage(const InlineImage &inlineImage, const GlsBool checkForDuplicate)
GlsImage * FindImageFromInlineImage(const InlineImage &inlineImage) const
Definition: gls_image.h:67
Definition: gls_image.h:235
unsigned int GlsUInt32
Definition: gls_types.h:73
GlsBool IsEqual(const InlineImage &inlineImage) const
This header defines the GL State Manager class for managing the GL state in the GL Studio DO-178B Run...
ImageCodec
Definition: gls_image.h:65
This header defines any preprocessor defines needed to configure the GL Studio DO-178B Runtime Librar...
const GlsUInt32 imageDataSize
Definition: gls_image.h:97
const GlsUInt32 _width
Definition: gls_image.h:249
GLuint _textureHandle
Definition: gls_image.h:247
ImageList(const GlsUInt32 maxNumImages)
GlsImage(const InlineImage &inlineImage)
Definition: gls_image.h:68
This header defines a GLS_DEBUG only macro for facilitating evaluating class invariants in the GL Stu...
const GlsUInt32 height
Definition: gls_image.h:93
const GlsUInt32 width
Definition: gls_image.h:92
Definition: gls_image.h:59
static const GlsUInt32 NUM_BYTES_PER_INPUT_PIXEL_FORMAT_ALPHA
Definition: gls_image.h:245
GlsUInt32 PixelSizeFromInputPixelFormat(const GlsImage::InputPixelFormat inputPixelFormat) const
Definition: gls_image.h:233
const InputPixelFormat _inputPixelFormat
Definition: gls_image.h:248
Definition: gls_image.h:112
const GlsUChar *const * imageData
Definition: gls_image.h:99
Definition: gls_image.h:234
static const GlsUInt32 NUM_BYTES_PER_INPUT_PIXEL_FORMAT_RGB
Definition: gls_image.h:241
static const GLuint INVALID_TEXTURE_HANDLE
Definition: gls_image.h:228
Definition: gls_image.h:173
GlsUInt32 _numImages
Definition: gls_image.h:202
GlsPointerArray _images
Definition: gls_image.h:203
const GlsUInt32 lineLength
Definition: gls_image.h:98
const ImageCodec codec
Definition: gls_image.h:95
const GlsUInt32 maxImageWidth
Definition: gls_image.h:115
static ImageList * _imageList
Definition: gls_image.h:253
const InputPixelFormat inputPixelFormat
Definition: gls_image.h:94
Definition: gls_image.h:90
void DecodeImage(const InlineImage &inlineImage)