[PloobsEngine] Tutorial 5 – Initialization Parameters


This tutorial will talk about the PloobsEngine Initialization Parameters. (tutorials series here)

The tutorials so far used some “curious” options when initializing the engine, now we will talk about each of those misterious choices. =P

In every engine sample, we have the following block of the code (when starting the engine).

            InitialEngineDescription desc = InitialEngineDescription.Default();
            ///start the engine
            using (EngineStuff engine = new EngineStuff(ref desc, LoadScreen))
            {
                engine.Run();
            }

We are just creating a simple object describing the engine initialization confs, providing it to the EngineStuff constructor and starting the PloobsEngine workflow.

Now we will talk about the InitialEngineDescription object in depth.

We can create the InitialEngineDescription using the static method Default or using the detained constructor. The following block discuss a little about the parameters you can change in this object.

  • BackBufferHeight: the resolution of the screen in Y (if windowed also controls the Y size of the screen)
  • BackBufferWidth: the resolution of the screen in X (if windowed also controls the X size of the screen)
  • isFullScreen: If true, the game will run in fullscreen mode, if not, windowed.
  • GraphicsProfile: The engine only support HiDef profile in this release. We plan to use this field to load in run time the right DLL for the users.
  • isFixedGameTime: If true, the engine will force the game to be 60 FPS (and will try to ensure the game has this minimum FPS, if it is slower than this, the draw method  will be called less times). When debuggingm i suggest to turn this off (so the FPS will be real).
  • isMultiSampling: to use force using Multisampling  (Anti Aliasing method). This ONLY works in Forward Rendering. If you enable this in deferred we will use Multisampling but the quality wont be improved a lot (cause under XNA (DirectX 9c) we dont have Multisample when using Multiple Render Targets). We suggest to turn this off in lower specs PCs when Deferred Render is used. Under Deferred Render, try using Post effects AA technichs (will be explained in next tutorials =P)
  • Logger: Interface provided by the user (can be null) where the engine logs problems (will be discussed more later in this article)
  • OnExit: Event called when the engine exits
  • ScreenName: The name you want to the engine screen
  • UnhandledException_Handlerquality
  • UseAnisotropicFiltering: Use Anisotropic Filtering instead of Linear filtering when possible (better quality but slower)
  • useMipMapWhenPossible: Improve Texture filtering using MipMaps when possible (better quality but slower)
  • UseVerticalSyncronization: Sync the graphics drawing with the monitor refresj frequency (recomended, but forces the draw FPS to 60)

Engine Default

When you call the static method Default of the the InitialEngineDescription, the following options are used:

public InitialEngineDescription(string ScreenName = "PloobsEngine", int BackBufferWidth = 800, int BackBufferHeight = 600, bool isFullScreen = false, GraphicsProfile graphicsProfile = GraphicsProfile.HiDef, bool useVerticalSyncronization = false, bool isMultiSampling = false, bool isFixedGameTime = false, ILogger logger = null, bool useMipMapWhenPossible = false, bool UseAnisotropicFiltering = false);

ILogger

The PloobsEngine Debug DLL (the one provided) sometimes logs messages to the user. These messages can be:

  • Warnings: Whe the user does something that is not wrong, but normally is not what “user wants” to do. The message is just a “Are you sure you want to do this ???”
  • Recoverable Errors: When the user make a error somewhere, but the engine can recover from it (THE USER SHOULD correct the source of the problem), normally the engine aborts the current operation when recoverable  errors happens, ao unexpected stuffs can happen.
  • Fatal Error: This happens when the user does something that CANNOT be done. This is normally folowed by an Exception being thrown.

The user can provide a implementation of the interface ILogger to the InitialEngineDescription object (if not provided, nothing is logged … we STRONGLY recomend implementing this). The following code show the interface:

public interface ILogger
    {
        void Log(string Message, LogLevel logLevel);
    }

It is pretty simple, you override the Log method. The LogLevel can be Warning, Fatal Error and Recoverable Error as dicussed. We tried to not use the ILogger in code that runs everytime, so you can write to files, write to server … in the implementation (we suggest you to dont do this in production code, try to use Threads or something assync to proccess the message).In debug a simple Debug.WriteLine is enough =P

Users can also log messager using this log system. Just use the following static method: (everywhere, after the EngineStuff constructor)

PloobsEngine.Engine.Logger.ActiveLogger.LogMessage(message,PloobsEngine.Engine.Logger.LogLevel.LOGLEVEL_YOU_WANT);

Unhandled Exception

Sometimes, the engine can throw exeptions to the user (When fatal error happens (user mistake),when XNA/Windows fails, when engine bugs decide to appear =P … ). The engine normally does catch those exception, so the user can handle them (you cant recover, your job is to “something” like write to a log file or server, before the end the of the execution). To use this funcionality, you just need to provide a method with the following signature to the InitialEngineDescription.

public delegate void UnhandledException(object sender, UnhandledExceptionEventArgs e);

Its all for today (small tutorial =P)

Any doubts, critics, suggestions, pls go to our forum or leave a comment here.

See you guys =P

Links

 

, , , ,