Doc/to_port/Image.dox

   1 #include <OSGConfig.h>
   2
   3 using namespace OSG;
   4
   5 /*! \defgroup GrpSystemImage Image
   6     \ingroup GrpSystem
   7
   8     See \ref PageSystemImage for a description.
   9 */
  10
  11 /*! \page PageSystemImage Image
  12
  13 \latexonly Starter:NewChapter \endlatexonly
  14
  15 Defines and holds a 1D/2D/3D image and optionally a mipmap pyramid and/or a
  16 list of equally sized frames with a single frameDelay. Various pixelTypes are
  17 supported to handle gray and RGB color images with or without alpha channel.
  18
  19 An Image is only a container for the pixel data and image description. It does
  20 not create or handle any OpenGL state elements. However, image objects are
  21 utilized to handle the data for texture (e.g. osg::SimpleTextureMaterial or
  22 osg::TextureChunk) or  bitmap objects (e.g. osg::ImageForeground).
  23
  24 The image object holds some describing fields (e.g. width/height/depth),
  25 and a single block of memory for all the raster data.
  26
  27 \image html image-mmm.png "Mem layout for Multi-Frame mip-map image data"
  28 \image latex image-mmm.eps "Mem layout for Multi-Frame mip-map image data" width=14cm
  29
  30 The image data starts in the lower left (front) corner and all bytes for a
  31 single pixel (e.g. RGB) are stored sequentially in memory. They are not
  32 organized in separate layers or channels.
  33
  34 The optional mipmap-level are stored directly after the Image
  35 data. The dimensions (width/height/depth) are always reduced to 50%
  36 of the previous level but stay at least 1. The Image object can hold
  37 just a number of levels and must not be complete (end with a 1x1x1 level).
  38
  39 If there are any additional mipmap-levels defined, OpenSG will use
  40 the data turing the texture-upload process.
  41 If the image does not contain mipmap levels, which is true in
  42 most cases, OpenSG will use OpenGL functions to create the level
  43 direclty as OpenGL objects. The System will not change the
  44 image object for rendering. Therefore, the ability to define
  45 the mipmap levels is rarely needed but very usefull
  46 (e.g. Real-Time Hatching).
  47
  48 The pyramid (at least one Level) defines a frame. All frames
  49 are stored after each other separately starting with frame 0.
  50
  51 If the user loads a multi-frame image and assigns the
  52 object to a osg::TextureChunk
  53 it is not played automatically as movie.
  54 The Application has to set and change the 'current' frame in the
  55 TextureChunk.
  56
  57 The Image Class implementation does not include Image-Processing
  58 functionality, but provides some simple funktions to scale and crop
  59 and to set subregions of the data.
  60
  61 The system provides loaders and writers for various formats including
  62 png, jpeg, tiff, gif and sgi. In addition a specific mtd
  63 (multi texture data) reader/writer is included. The mtd file
  64 format is a simple platform independent header and binary
  65 dump of the Image object data. It is the only format which can
  66 hold all field and data properties of the OpenSG Image.
  67
  68 The graph loaders (e.g. OSGLoader, VRMLLoader) use the image loaders
  69 to fetch the raster data.
  70
  71 */