include/SIrrCreationParameters.h

   1 // Copyright (C) 2002-2012 Nikolaus Gebhardt\r
   2 // This file is part of the "Irrlicht Engine".\r
   3 // For conditions of distribution and use, see copyright notice in irrlicht.h\r
   4 \r
   5 #ifndef __I_IRRLICHT_CREATION_PARAMETERS_H_INCLUDED__\r
   6 #define __I_IRRLICHT_CREATION_PARAMETERS_H_INCLUDED__\r
   7 \r
   8 #include "EDriverTypes.h"\r
   9 #include "EDeviceTypes.h"\r
  10 #include "dimension2d.h"\r
  11 #include "ILogger.h"\r
  12 #include "position2d.h"\r
  13 #include "path.h"\r
  14 #include "IrrCompileConfig.h" // for IRRLICHT_SDK_VERSION\r
  15 \r
  16 namespace irr\r
  17 {\r
  18         class IEventReceiver;\r
  19 \r
  20         //! Structure for holding Irrlicht Device creation parameters.\r
  21         /** This structure is used in the createDeviceEx() function. */\r
  22         struct SIrrlichtCreationParameters\r
  23         {\r
  24                 //! Constructs a SIrrlichtCreationParameters structure with default values.\r
  25                 SIrrlichtCreationParameters() :\r
  26                         DeviceType(EIDT_BEST),\r
  27                         DriverType(video::EDT_BURNINGSVIDEO),\r
  28                         WindowSize(core::dimension2d<u32>(800, 600)),\r
  29                         WindowPosition(core::position2di(-1,-1)),\r
  30                         Bits(32),\r
  31                         ZBufferBits(24),\r
  32                         Fullscreen(false),\r
  33                         WindowMaximized(false),\r
  34                         WindowResizable(2),\r
  35                         Stencilbuffer(true),\r
  36                         Vsync(false),\r
  37                         AntiAlias(0),\r
  38                         HandleSRGB(false),\r
  39                         WithAlphaChannel(false),\r
  40                         Doublebuffer(true),\r
  41                         IgnoreInput(false),\r
  42                         Stereobuffer(false),\r
  43                         HighPrecisionFPU(false),\r
  44                         EventReceiver(0),\r
  45                         WindowId(0),\r
  46 #ifdef _DEBUG\r
  47                         LoggingLevel(ELL_DEBUG),\r
  48 #else\r
  49                         LoggingLevel(ELL_INFORMATION),\r
  50 #endif\r
  51                         DisplayAdapter(0),\r
  52                         DriverMultithreaded(false),\r
  53                         UsePerformanceTimer(true),\r
  54                         SDK_version_do_not_use(IRRLICHT_SDK_VERSION),\r
  55                         PrivateData(0),\r
  56 #ifdef IRR_MOBILE_PATHS\r
  57                         OGLES2ShaderPath("media/Shaders/")\r
  58 #else\r
  59                         OGLES2ShaderPath("../../media/Shaders/")\r
  60 #endif\r
  61                 {\r
  62                 }\r
  63 \r
  64                 SIrrlichtCreationParameters(const SIrrlichtCreationParameters& other) :\r
  65                         SDK_version_do_not_use(IRRLICHT_SDK_VERSION)\r
  66                 {*this = other;}\r
  67 \r
  68                 SIrrlichtCreationParameters& operator=(const SIrrlichtCreationParameters& other)\r
  69                 {\r
  70                         DeviceType = other.DeviceType;\r
  71                         DriverType = other.DriverType;\r
  72                         WindowSize = other.WindowSize;\r
  73                         WindowPosition = other.WindowPosition;\r
  74                         Bits = other.Bits;\r
  75                         ZBufferBits = other.ZBufferBits;\r
  76                         Fullscreen = other.Fullscreen;\r
  77                         WindowMaximized = other.WindowMaximized;\r
  78                         WindowResizable = other.WindowResizable;\r
  79                         Stencilbuffer = other.Stencilbuffer;\r
  80                         Vsync = other.Vsync;\r
  81                         AntiAlias = other.AntiAlias;\r
  82                         HandleSRGB = other.HandleSRGB;\r
  83                         WithAlphaChannel = other.WithAlphaChannel;\r
  84                         Doublebuffer = other.Doublebuffer;\r
  85                         IgnoreInput = other.IgnoreInput;\r
  86                         Stereobuffer = other.Stereobuffer;\r
  87                         HighPrecisionFPU = other.HighPrecisionFPU;\r
  88                         EventReceiver = other.EventReceiver;\r
  89                         WindowId = other.WindowId;\r
  90                         LoggingLevel = other.LoggingLevel;\r
  91                         DisplayAdapter = other.DisplayAdapter;\r
  92                         DriverMultithreaded = other.DriverMultithreaded;\r
  93                         UsePerformanceTimer = other.UsePerformanceTimer;\r
  94                         PrivateData = other.PrivateData;\r
  95                         OGLES2ShaderPath = other.OGLES2ShaderPath;\r
  96                         return *this;\r
  97                 }\r
  98 \r
  99                 //! Type of the device.\r
 100                 /** This setting decides the windowing system used by the device, most device types are native\r
 101                 to a specific operating system and so may not be available.\r
 102                 EIDT_WIN32 is only available on Windows desktops,\r
 103                 EIDT_COCOA is only available on Mac OSX,\r
 104                 EIDT_X11 is available on Linux, Solaris, BSD and other operating systems which use X11,\r
 105                 EIDT_SDL is available on most systems if compiled in,\r
 106                 EIDT_BEST will select the best available device for your operating system.\r
 107                 Default: EIDT_BEST. */\r
 108                 E_DEVICE_TYPE DeviceType;\r
 109 \r
 110                 //! Type of video driver used to render graphics.\r
 111                 /** This can currently be video::EDT_NULL, video::EDT_SOFTWARE,\r
 112                 video::EDT_BURNINGSVIDEO, video::EDT_DIRECT3D9, and video::EDT_OPENGL.\r
 113                 Default: EDT_BURNINGSVIDEO. */\r
 114                 video::E_DRIVER_TYPE DriverType;\r
 115 \r
 116                 //! Size of the window or the video mode in fullscreen mode. Default: 800x600\r
 117                 core::dimension2d<u32> WindowSize;\r
 118 \r
 119                 //! Position of the window on-screen. Default: (-1, -1) or centered.\r
 120                 core::position2di WindowPosition;\r
 121 \r
 122                 //! Minimum Bits per pixel of the color buffer in fullscreen mode. Ignored if windowed mode. Default: 32.\r
 123                 u8 Bits;\r
 124 \r
 125                 //! Minimum Bits per pixel of the depth buffer. Default: 24.\r
 126                 u8 ZBufferBits;\r
 127 \r
 128                 //! Should be set to true if the device should run in fullscreen.\r
 129                 /** Otherwise the device runs in windowed mode. Default: false. */\r
 130                 bool Fullscreen;\r
 131 \r
 132                 //! Maximised window. (Only supported on SDL.) Default: false\r
 133                 bool WindowMaximized;\r
 134 \r
 135                 //! Should a non-fullscreen window be resizable.\r
 136                 /** Might not be supported by all devices. Ignored when Fullscreen is true.\r
 137                 Values: 0 = not resizable, 1 = resizable, 2 = system decides default itself\r
 138                 Default: 2*/\r
 139                 u8 WindowResizable;\r
 140 \r
 141                 //! Specifies if the stencil buffer should be enabled.\r
 142                 /** Set this to true, if you want the engine be able to draw\r
 143                 stencil buffer shadows. Note that not all drivers are able to\r
 144                 use the stencil buffer, hence it can be ignored during device\r
 145                 creation. Without the stencil buffer no shadows will be drawn.\r
 146                 Default: true. */\r
 147                 bool Stencilbuffer;\r
 148 \r
 149                 //! Specifies vertical synchronization.\r
 150                 /** If set to true, the driver will wait for the vertical\r
 151                 retrace period, otherwise not. May be silently ignored.\r
 152                 Default: false */\r
 153                 bool Vsync;\r
 154 \r
 155                 //! Specifies if the device should use fullscreen anti aliasing\r
 156                 /** Makes sharp/pixelated edges softer, but requires more\r
 157                 performance. Also, 2D elements might look blurred with this\r
 158                 switched on. The resulting rendering quality also depends on\r
 159                 the hardware and driver you are using, your program might look\r
 160                 different on different hardware with this. So if you are\r
 161                 writing a game/application with AntiAlias switched on, it would\r
 162                 be a good idea to make it possible to switch this option off\r
 163                 again by the user.\r
 164                 The value is the maximal antialiasing factor requested for\r
 165                 the device. The creation method will automatically try smaller\r
 166                 values if no window can be created with the given value.\r
 167                 Value one is usually the same as 0 (disabled), but might be a\r
 168                 special value on some platforms. On D3D devices it maps to\r
 169                 NONMASKABLE.\r
 170                 Default value: 0 - disabled */\r
 171                 u8 AntiAlias;\r
 172 \r
 173                 //! Flag to enable proper sRGB and linear color handling\r
 174                 /** In most situations, it is desirable to have the color handling in\r
 175                 non-linear sRGB color space, and only do the intermediate color\r
 176                 calculations in linear RGB space. If this flag is enabled, the device and\r
 177                 driver try to assure that all color input and output are color corrected\r
 178                 and only the internal color representation is linear. This means, that\r
 179                 the color output is properly gamma-adjusted to provide the brighter\r
 180                 colors for monitor display. And that blending and lighting give a more\r
 181                 natural look, due to proper conversion from non-linear colors into linear\r
 182                 color space for blend operations. If this flag is enabled, all texture colors\r
 183                 (which are usually in sRGB space) are correctly displayed. However vertex colors\r
 184                 and other explicitly set values have to be manually encoded in linear color space.\r
 185                 Default value: false. */\r
 186                 bool HandleSRGB;\r
 187 \r
 188                 //! Whether the main framebuffer uses an alpha channel.\r
 189                 /** In some situations it might be desirable to get a color\r
 190                 buffer with an alpha channel, e.g. when rendering into a\r
 191                 transparent window or overlay. If this flag is set the device\r
 192                 tries to create a framebuffer with alpha channel.\r
 193                 If this flag is set, only color buffers with alpha channel\r
 194                 are considered. Otherwise, it depends on the actual hardware\r
 195                 if the colorbuffer has an alpha channel or not.\r
 196                 Default value: false */\r
 197                 bool WithAlphaChannel;\r
 198 \r
 199                 //! Whether the main framebuffer uses doublebuffering.\r
 200                 /** This should be usually enabled, in order to avoid render\r
 201                 artifacts on the visible framebuffer. However, it might be\r
 202                 useful to use only one buffer on very small devices. If no\r
 203                 doublebuffering is available, the drivers will fall back to\r
 204                 single buffers. Default value: true */\r
 205                 bool Doublebuffer;\r
 206 \r
 207                 //! Specifies if the device should ignore input events\r
 208                 /** This is only relevant when using external I/O handlers.\r
 209                 External windows need to take care of this themselves.\r
 210                 Currently only supported by X11.\r
 211                 Default value: false */\r
 212                 bool IgnoreInput;\r
 213 \r
 214                 //! Specifies if the device should use stereo buffers\r
 215                 /** Some high-end gfx cards support two framebuffers for direct\r
 216                 support of stereoscopic output devices. If this flag is set the\r
 217                 device tries to create a stereo context.\r
 218                 Currently only supported by OpenGL.\r
 219                 Default value: false */\r
 220                 bool Stereobuffer;\r
 221 \r
 222                 //! Specifies if the device should use high precision FPU setting\r
 223                 /** This is only relevant for DirectX Devices, which switch to\r
 224                 low FPU precision by default for performance reasons. However,\r
 225                 this may lead to problems with the other computations of the\r
 226                 application. In this case setting this flag to true should help\r
 227                 - on the expense of performance loss, though.\r
 228                 Default value: false */\r
 229                 bool HighPrecisionFPU;\r
 230 \r
 231                 //! A user created event receiver.\r
 232                 IEventReceiver* EventReceiver;\r
 233 \r
 234                 //! Window Id.\r
 235                 /** If this is set to a value other than 0, the Irrlicht Engine\r
 236                 will be created in an already existing window.\r
 237                 For Windows, set this to the HWND of the window you want.\r
 238                 For iOS, assign UIView to this variable.\r
 239                 The windowSize and FullScreen options will be ignored when using\r
 240                 the WindowId parameter. Default this is set to 0.\r
 241                 To make Irrlicht run inside the custom window, you still will\r
 242                 have to draw Irrlicht on your own. You can use this loop, as\r
 243                 usual:\r
 244                 \code\r
 245                 while (device->run())\r
 246                 {\r
 247                         driver->beginScene(video::ECBF_COLOR | video::ECBF_DEPTH, 0);\r
 248                         smgr->drawAll();\r
 249                         driver->endScene();\r
 250                 }\r
 251                 \endcode\r
 252                 Instead of this, you can also simply use your own message loop\r
 253                 using GetMessage, DispatchMessage and whatever. Calling\r
 254                 IrrlichtDevice::run() will cause Irrlicht to dispatch messages\r
 255                 internally too.  You need not call Device->run() if you want to\r
 256                 do your own message dispatching loop, but Irrlicht will not be\r
 257                 able to fetch user input then and you have to do it on your own\r
 258                 using the window messages, DirectInput, or whatever. Also,\r
 259                 you'll have to increment the Irrlicht timer.\r
 260                 An alternative, own message dispatching loop without\r
 261                 device->run() would look like this:\r
 262                 \code\r
 263                 MSG msg;\r
 264                 while (true)\r
 265                 {\r
 266                         if (PeekMessage(&msg, NULL, 0, 0, PM_REMOVE))\r
 267                         {\r
 268                                 TranslateMessage(&msg);\r
 269                                 DispatchMessage(&msg);\r
 270 \r
 271                                 if (msg.message == WM_QUIT)\r
 272                                         break;\r
 273                         }\r
 274 \r
 275                         // increase virtual timer time\r
 276                         device->getTimer()->tick();\r
 277 \r
 278                         // draw engine picture\r
 279                         driver->beginScene(video::ECBF_COLOR | video::ECBF_DEPTH, 0);\r
 280                         smgr->drawAll();\r
 281                         driver->endScene();\r
 282                 }\r
 283                 \endcode\r
 284                 However, there is no need to draw the picture this often. Just\r
 285                 do it how you like. */\r
 286                 void* WindowId;\r
 287 \r
 288                 //! Specifies the logging level used in the logging interface.\r
 289                 /** The default value is ELL_INFORMATION. You can access the ILogger interface\r
 290                 later on from the IrrlichtDevice with getLogger() and set another level.\r
 291                 But if you need more or less logging information already from device creation,\r
 292                 then you have to change it here.\r
 293                 */\r
 294                 ELOG_LEVEL LoggingLevel;\r
 295 \r
 296                 //! Allows to select which graphic card is used for rendering when more than one card is in the system.\r
 297                 /** So far only supported on D3D */\r
 298                 u32 DisplayAdapter;\r
 299 \r
 300                 //! Create the driver multithreaded.\r
 301                 /** Default is false. Enabling this can slow down your application.\r
 302                         Note that this does _not_ make Irrlicht threadsafe, but only the underlying driver-API for the graphiccard.\r
 303                         So far only supported on D3D. */\r
 304                 bool DriverMultithreaded;\r
 305 \r
 306                 //! Enables use of high performance timers on Windows platform.\r
 307                 /** When performance timers are not used, standard GetTickCount()\r
 308                 is used instead which usually has worse resolution, but also less\r
 309                 problems with speed stepping and other techniques.\r
 310                 */\r
 311                 bool UsePerformanceTimer;\r
 312 \r
 313                 //! Don't use or change this parameter.\r
 314                 /** Always set it to IRRLICHT_SDK_VERSION, which is done by default.\r
 315                 This is needed for sdk version checks. */\r
 316                 const c8* const SDK_version_do_not_use;\r
 317 \r
 318                 //! Define some private data storage.\r
 319                 /** Used when platform devices need access to OS specific data structures etc.\r
 320                 This is only used for Android at th emoment in order to access the native\r
 321                 Java RE. */\r
 322                 void *PrivateData;\r
 323 \r
 324                 //! Set the path where default-shaders to simulate the fixed-function pipeline can be found.\r
 325                 /** This is about the shaders which can be found in media/Shaders by default. It's only necessary\r
 326                 to set when using OGL-ES 2.0 */\r
 327                 irr::io::path OGLES2ShaderPath;\r
 328         };\r
 329 \r
 330 \r
 331 } // end namespace irr\r
 332 \r
 333 #endif\r
 334 \r