SharkVisualisation Documentation, generated with mkdoc

Last update 27/Jul/2008 by Mark Seuffert
Overview:
1.       Introduction
2.1.    CBase3d
2.2.    CBaseController
2.3.    CBaseManager
2.4.    CConsole
2.5.    CFont
2.6.    CFontManager
2.7.    CImagePng
2.8.    CImageTga
2.9.    CInput
2.10.  CModel
2.11.  CModelManager
2.12.  CModelMs3d
2.13.  CTexture
2.14.  CTextureManager
2.15.  CTimer
2.16.  CWindow
2.17.  IObjectInterface
2.18.  Misc

1. Introduction

This is a documentation about the SharkVisualisation library. SharkVisualisation is an object oriented visualisation library, it allows to use the same code on different platforms. Shared libraries are available for C++ on Linux, BSD and Windows.
Feature highlights:
  • 3D visualisation with OpenGL
  • reading PNG, TGA and MS3D (Milkshape 3D) data formats
  • not binary dependent on a specific version of STL or Boost
SharkVisualisation will be later included in the Pichat SDK. Please note that this visualisation library is purely experimental and currently available for registered users and friends only.

2.1. CBase3d

Description: 3D visualisation base class
Header file: SharkVisualisation_Classes.h, namespace SharkVisualisation
Comments: This class provides a base for 3D visualisation with OpenGL. It supports input handling, text output, drawing 3D models and windows with or without own event pump. Derive your own class from this and overload the virtual methods you need.
These virtual methods exist:
  • OnMainLoopStart() informs that main loop is starting
  • OnCreate3dWindow() informs that window has been created
  • OnAnimate() animate and update objects
  • OnRender() render objects
  • OnRenderOverlay() render objects on top
  • OnDestroy3dWindow() informs that window will be destroyed
  • OnMainLoopStop() informs that main loop is stopping
These public member variables exist:
m_pConsoleconsole and logging (owned)
m_pTimerhigh resolution timer for main loop (owned)
m_pWindowOpenGL window (owned)
m_pInputinput (owned)
m_pTextureManagertexture manager (owned)
m_pFontManagerfont manager (owned)
m_pModelManagermodel manager (owned)
Construction
Syntax:CBase3d();
CBase3d(const char* szWindowTitle, int nWidth, int nHeight, int nColordeDepth, bool bFullScreen, const char* szLogfileName, int nLogLevel, int nLogMode);
Constants
components (bits):
COMPONENT_NONEno component
COMPONENT_LOGFILElogfile
COMPONENT_TIMERtimer
COMPONENT_WINDOWwindow
COMPONENT_TEXTUREtexture
COMPONENT_FONTfont
COMPONENT_MODELmodel
COMPONENT_CUSTOMcustom components, free for use
Create - Create visualisation
Syntax:bool Create(const char* szWindowTitle, int nWidth, int nHeight, int nColordeDepth, bool bFullScreen, const char* szLogfileName, int nLogLevel, int nLogMode);
Destroy - Destroy visualisation
Syntax:void Destroy();
Run - Start main loop and event pump
Syntax:bool Run();
Stop - Stop main loop and event pump
Syntax:void Stop();
Create3dWindow - Create 3D window
Syntax:bool Create3dWindow();
Destroy3dWindow - Destroy 3D window
Syntax:void Destroy3dWindow();
SetResolution - Set window resolution
Syntax:bool SetResolution(int nWidth, int nHeight, int nColorDepth);
SetUpdatePaint - Set time intervall for extra paint updates
Syntax:void SetUpdatePaint(DWORD dwUpdatePaint);
SetIcon - Set window icon
Syntax:void SetIcon(HICON hIcon, BYTE* pMask = NULL);
void SetIcon(HMODULE hResourceModule, int nResourceID);
ToggleFullscreen - Toggle between fullscreen and windowed mode
Syntax:void ToggleFullscreen();
SetParentWindow - Set parent window handle
Syntax:void SetParentWindow(HWND hWndParent);
GetParentWindow - Return parent window handle
Syntax:HWND GetParentWindow() const;
GetWindowHandle - Return window handle
Syntax:HWND GetWindowHandle() const;
GetResolution - Return window resolution
Syntax:void GetResolution(int& nWidth, int& nHeight, int& nColorDepth) const;
GetWidth - Return current window width (pixel)
Syntax:int GetWidth() const;
GetHeight - Return current window height (pixel)
Syntax:int GetHeight() const;
GetColorDepth - Return window color depth (bits per pixel)
Syntax:int GetColorDepth() const;
GetFps - Return average frames per second (FPS)
Syntax:int GetFps(int nTimeDuration = 500);
GetKey - Return if key was pressed
Syntax:bool GetKey(int nKey);
bool GetKeyState(int nKey) const;
GetError - Return component error flags
Syntax:int GetError() const;
SetErrorFlag - Set component error flag
Syntax:void SetErrorFlag(int nComponent);
IsErrorFlag - Check if component error flag is set
Syntax:bool IsErrorFlag(int nComponent) const;
IsErrorCritical - Return if error status is critical
Syntax:bool IsErrorCritical() const;
IsCreated - Check if visualisation is created
Syntax:bool IsCreated() const;
IsEventPump - Check if event pump is running
Syntax:bool IsEventPump() const;
IsRunning - Check if main loop is running
Syntax:bool IsRunning() const;
Output - Write text to console and logfile
Syntax:bool Output(int nLogLevel, const char* szText, ...);
OutputConsole - Write text to console
Syntax:void OutputConsole(const char* szText, ...);
ShowConsole - Show or hide console
Syntax:void ShowConsole(bool bShow = true);
ToggleConsole - Toggle console
Syntax:void ToggleConsole();
ReopenLogfile - Reopen logfile
Syntax:bool ReopenLogfile(bool bAppend = true);
SetLogLevel - Set logging settings
Syntax:void SetLogLevel(int nLogLevel, int nLogMode);
GetLogLevel - Return logging settings
Syntax:void GetLogLevel(int& nLogLevel, int& nLogMode) const;
GetComponentFormated - Return human readable component
Syntax:static SharkEngine::CString8 GetComponentFormated(int nComponent);

2.2. CBaseController

Description: Communication between 3D visualisation classes
Header file: SharkVisualisation_Classes.h, namespace SharkVisualisation
These public member variables exist:
m_pBaseaccess to 3D visualisation base class (and other classes)
m_pConsoleaccess to console and logging
Construction
Syntax:CBaseController();
IsReady - Check if controller and 3D visualisation classes are fully initialised
Syntax:IsReady() const;

2.3. CBaseManager

Description: Data manager base class
Header file: SharkVisualisation_Classes.h, namespace SharkVisualisation
Construction
Syntax:CBaseManager(CBaseController* pController);
Constants
OBJECT_INDEX_NONE = -1
MANAGER_DATA_SIZE = 100
Add - Add object
Notes: Returns index of object or OBJECT_INDEX_NONE in case of error. The given object must have been allocated with a C++ new operator and will be owned by the data manager.
Syntax:int Add(IObjectInterface* pObject, const char* szFileName, GLfloat fMinfilter = GL_NEAREST, GLfloat fMaxfilter = GL_NEAREST);
int Add(IObjectInterface* pObject, const char* szFileName, HMODULE hResourceModule, int nResourceID, const char* szResourceType = SharkEngine::ENGINE_RESOURCE_TYPE, GLfloat fMinfilter = GL_NEAREST, GLfloat fMaxfilter = GL_NEAREST);
Remove - Remove object
Syntax:void Remove(int nIndex);
Clear - Clear all objects
Syntax:void Clear();
GetObject - Return pointer to object or NULL if not found
Syntax:IObjectInterface* GetObject(int nIndex) const;
GetSize - Return number of handled objects
Syntax:int GetSize() const;
IsObject - Check if index is an object
Syntax:bool IsObject(int nIndex) const;
IsEmpty - Check if data manager is empty
Syntax:bool IsEmpty() const;
GetFileType - Return file type based on file extension
Notes: Returns position in comma separated list of file extension or zero if not found.
Syntax:static int GetFileType(const char* szFileName, const char* szFileExtensions);

2.4. CConsole

Description: Console display and logging
Header file: SharkVisualisation_Classes.h, namespace SharkVisualisation
Construction
Syntax:CConsole(CBaseController* pController);
Constants
log levels:
LOG_LEVEL_1log level 1, least details
LOG_LEVEL_2log level 2
LOG_LEVEL_3log level 3
LOG_LEVEL_4log level 4, most details
LOG_ERRORlog error
 
log modes:
LOG_MODE_NONEno logging
LOG_MODE_CONSOLElogging to console
LOG_MODE_FILElogging to file
LOG_MODE_BOTHlogging to console and file
 
CONSOLE_BUFFER_SIZE = 99, CONSOLE_BUFFER_MAXLINE = 120
Create - Create console and logging
Syntax:bool Create(const char* szLogfileName, int nLogLevel, int nLogMode);
Destroy - Destroy console and logging
Syntax:void Destroy();
Clear - Clear console content
Syntax:void Clear();
Output - Write text to console and logfile
Syntax:bool Output(int nLogLevel, const char* szText, ...);
bool OutputV(int nLogLevel, const char* szText, va_list argptr);
OutputConsole - Write text to console only
Syntax:void OutputConsole(const char* szText, ...);
void OutputConsoleV(const char* szText, va_list argptr);
Show - Show or hide console
Syntax:void Show(bool bShow = true);
Render - Draw console on screen
Syntax:void Render(bool bIsOrthoScreen = false);
ReopenLogfile - Reopen logfile
Syntax:bool ReopenLogfile(bool bAppend = true);
SetLogLevel - Set logging parameters
Syntax:void SetLogLevel(int nLogLevel, int nLogMode);
GetLogLevel - Return logging settings
Syntax:void GetLogLevel(int& nLogLevel, int &nLogMode) const;
IsCreated - Return if console is created
Syntax:bool IsCreated() const;
IsVisible - Return if console is visible
Syntax:bool IsVisible() const;

2.5. CFont

Description: Font
Header file: SharkVisualisation_Classes.h, namespace SharkVisualisation
These public member variables exist:
m_nTypefont type
m_fontfont data
Construction
Syntax:CFont();
Constants
font types:
TYPE_NONEno font loaded
TYPE_TEXTURE_MAPPEDtexture mapped font
Load - Load font
Syntax:virtual bool Load(const char* szFileName, SharkEngine::CFileStream& file, GLfloat fMinfilter, GLfloat fMaxfilter, CBaseController* pController);
Unload - Unload font
Syntax:virtual void Unload();
GetComponent - Return visualisation component, i.e. COMPONENT_FONT
Syntax:virtual int GetComponent() const;
IsLoaded - Check if font is loaded
Syntax:virtual bool IsLoaded() const;

2.6. CFontManager

Description: Font manager
Header file: SharkVisualisation_Classes.h, namespace SharkVisualisation
Construction
Syntax:CFontManager(CBaseController* pController);
Add - Add font
Notes: Returns index of object or OBJECT_INDEX_NONE in case of error.
Syntax:int Add(const char* szFileName, GLfloat fMinfilter = GL_NEAREST, GLfloat fMaxfilter = GL_NEAREST);
int Add(const char* szFileName, HMODULE hResourceModule, int nResourceID, const char* szResourceType = SharkEngine::ENGINE_RESOURCE_TYPE, GLfloat fMinfilter = GL_NEAREST, GLfloat fMaxfilter = GL_NEAREST);
Remove - Remove font
Syntax:void Remove(int nIndex);
DrawText - Draw text
Syntax:void DrawText(const char* szText, GLint x, GLint y);
SetFont - Set active font
Notes: The last added font becomes automatically the active font.
Syntax:void SetFont(int nIndex);

2.7. CImagePng

Description: PNG image decoder (Portable Network Graphics)
Header file: SharkVisualisation_Classes.h, namespace SharkVisualisation
Comments: Implements PNG format as defined in RFC 2083. It supports compressed and uncompressed images with optional alpha channel. This PNG decoder has been originally coded by David Fehrmann for Pichat.
Open issues:
- quantized images are not correctly handled
- pixels are only squares, phys chunk is ignored
- background & gamma colors need to be processed
- check bits for safe-to-copy bit, ancillary bit and private bit
Construction
Syntax:CImagePng();
LoadFromMemory - Load and decode image into buffer
Syntax:bool LoadFromMemory(const BYTE* pData, int nDataLen, bool bConvert32 = false, bool bAlign32 = false);
ClearBuffer - Clear image buffer
Syntax:void ClearBuffer();
GetBuffer - Return pointer to image buffer, allows direct buffer manipulation
Syntax:BYTE* GetBuffer();
GetBufferConst - Return pointer to non-modifiable image buffer, const version
Syntax:const BYTE* GetBufferConst() const;
GetBufferSize - Return size of image in buffer
Syntax:int GetBufferSize() const;
GetWidth - Return image width (pixel)
Syntax:int GetWidth() const;
GetHeight - Return image height (pixel)
Syntax:int GetHeight() const;
GetColorDepth - Return image color depth (bits per pixel)
Syntax:int GetColorDepth() const;
IsEmpty - Check if image buffer is empty
Syntax:bool IsEmpty() const;

2.8. CImageTga

Description: TGA image decoder (TARGA file format)
Header file: SharkVisualisation_Classes.h, namespace SharkVisualisation
Comments: Implements TGA format. It supports compressed and uncompressed images with optional alpha channel.
Construction
Syntax:CImageTga();
LoadFromMemory - Load and decode image into buffer
Syntax:bool LoadFromMemory(const BYTE* pData, int nDataLen);
ClearBuffer - Clear image buffer
Syntax:void ClearBuffer();
GetBuffer - Return pointer to image buffer, allows direct buffer manipulation
Syntax:BYTE* GetBuffer();
GetBufferConst - Return pointer to non-modifiable image buffer, const version
Syntax:const BYTE* GetBufferConst() const;
GetBufferSize - Return size of image in buffer
Syntax:int GetBufferSize() const;
GetWidth - Return image width (pixel)
Syntax:int GetWidth() const;
GetHeight - Return image height (pixel)
Syntax:int GetHeight() const;
GetColorDepth - Return image color depth (bits per pixel)
Syntax:int GetColorDepth() const;
IsEmpty - Check if image buffer is empty
Syntax:bool IsEmpty() const;

2.9. CInput

Description: Input handling
Header file: SharkVisualisation_Classes.h, namespace SharkVisualisation
Construction
Syntax:CInput(CBaseController* pController);
GetKey - Return if key was pressed and reset it
Syntax:bool GetKey(int nKey);
GetKeyState - Return if key was pressed
Syntax:bool GetKeyState(int nKey) const;

2.10. CModel

Description: Model
Header file: SharkVisualisation_Classes.h, namespace SharkVisualisation
These public member variables exist:
m_nTypemodel type
m_modelmodel data
Construction
Syntax:CModel();
Constants
model types:
TYPE_NONEno font loaded
TYPE_MODEL_MS3DMS3D model
Render - Render model
Syntax:void Render();
Load - Load model
Syntax:virtual bool Load(const char* szFileName, SharkEngine::CFileStream& file, GLfloat fMinfilter, GLfloat fMaxfilter, CBaseController* pController);
Unload - Unload model
Syntax:virtual void Unload();
GetComponent - Return visualisation component, i.e. COMPONENT_MODEL
Syntax:virtual int GetComponent() const;
IsLoaded - Check if model is loaded
Syntax:virtual bool IsLoaded() const;

2.11. CModelManager

Description: Model manager
Header file: SharkVisualisation_Classes.h, namespace SharkVisualisation
Construction
Syntax:CModelManager(CBaseController* pController);
Add - Add model
Notes: Returns index of object or OBJECT_INDEX_NONE in case of error.
Syntax:int Add(const char* szFileName, GLfloat fMinfilter = GL_NEAREST, GLfloat fMaxfilter = GL_NEAREST);
int Add(const char* szFileName, HMODULE hResourceModule, int nResourceID, const char* szResourceType = SharkEngine::ENGINE_RESOURCE_TYPE, GLfloat fMinfilter = GL_NEAREST, GLfloat fMaxfilter = GL_NEAREST);
Remove - Remove model
Syntax:void Remove(int nIndex);
Render - Render model
Syntax:void Render(int nIndex);

2.12. CModelMs3d

Description: MS3D model decoder (MilkShape 3D)
Header file: SharkVisualisation_Classes.h, namespace SharkVisualisation
Comments: Implements a very simple 3D model loader.
Open issues:
- load and render textures
- animated models are not handled
Construction
Syntax:CModelMs3d();
LoadFromMemory - Load model into buffer
Syntax:bool LoadFromMemory(const BYTE* pData, int nDataLen);
ClearBuffer - Clear model buffer
Syntax:void ClearBuffer();
GetBuffer - Return pointer to model buffer, allows direct buffer manipulation
Syntax:Model* GetBuffer();
GetBufferConst - Return pointer to non-modifiable model buffer, const version
Syntax:const Model* GetBufferConst() const;
IsEmpty - Check if model buffer is empty
Syntax:bool IsEmpty() const;

2.13. CTexture

Description: Texture
Header file: SharkVisualisation_Classes.h, namespace SharkVisualisation
These public member variables exist:
m_nTypetexture type
m_texturetexture data
Construction
Syntax:CTexture();
Constants
texture types:
TYPE_NONEno texture loaded
TYPE_IMAGE_TGAtexure from TGA image
TYPE_IMAGE_PNGtexure from PNG image
Render - Render texture on a quad
Syntax:void Render();
Load - Load texture
Syntax:virtual bool Load(const char* szFileName, SharkEngine::CFileStream& file, GLfloat fMinfilter, GLfloat fMaxfilter, CBaseController* pController);
Unload - Unload texture
Syntax:virtual void Unload();
GetComponent - Return visualisation component, i.e. COMPONENT_TEXTURE
Syntax:virtual int GetComponent() const;
IsLoaded - Check if texture is loaded
Syntax:virtual bool IsLoaded() const;
IsValidTexture - Check if valid texture, both dimensions need to be 2^n
Syntax:static bool IsValidTexture(int nWidth, int nHeight);

2.14. CTextureManager

Description: Texture manager
Header file: SharkVisualisation_Classes.h, namespace SharkVisualisation
Construction
Syntax:CTextureManager(CBaseController* pController);
Add - Add texture
Notes: Returns index of object or OBJECT_INDEX_NONE in case of error.
Syntax:int Add(const char* szFileName, GLfloat fMinfilter = GL_NEAREST, GLfloat fMaxfilter = GL_NEAREST);
int Add(const char* szFileName, HMODULE hResourceModule, int nResourceID, const char* szResourceType = SharkEngine::ENGINE_RESOURCE_TYPE, GLfloat fMinfilter = GL_NEAREST, GLfloat fMaxfilter = GL_NEAREST);
Remove - Remove texture
Syntax:void Remove(int nIndex);
Render - Render texture on a quad
Syntax:void Render(int nIndex, int x, int y);
RenderMasked - Render texture on a quad with transparency mask
Syntax:void RenderMasked(int nIndex, int nIndexMask, int x, int y);

2.15. CTimer

Description: High resolution timer
Header file: SharkVisualisation_Classes.h, namespace SharkVisualisation
Construction
Syntax:CTimer(CBaseController* pController);
GetElapsedSeconds - Return how many time has been passed since last call
Syntax:float GetElapsedSeconds();
GetFps - Return average frames per second (FPS)
Syntax:int GetFps(int nTimeDuration = 500);
TriggerFps - Count another frame
Syntax:void TriggerFps();
Reset - Reset high resolution timer
Syntax:bool Reset();

2.16. CWindow

Description: OpenGL window
Header file: SharkVisualisation_Classes.h, namespace SharkVisualisation
Construction
Syntax:CWindow(CBaseController* pController);
Create - Create window
Syntax:bool Create();
Destroy - Destroy window
Syntax:void Destroy();
Set - Set window properties
Syntax:bool Set(const char* szWindowTitle, int nWidth, int nHeight, int nColordeDepth, bool bFullScreen);
SetResolution - Set window resolution
Syntax:bool SetResolution(int nWidth, int nHeight, int nColorDepth);
SetIcon - Set window icon
Syntax:void SetIcon(HICON hIcon, BYTE* pMask = NULL);
void SetIcon(HMODULE hResourceModule, int nResourceID);
SetDefaultIcon - Set default window icon
Syntax:void SetDefaultIcon();
SetUpdatePaint - Set time intervall for extra paint updates
Notes: This method is unused on Linux platform.
Syntax:void SetUpdatePaint(DWORD dwUpdatePaint);
SwapBuffers - Swap OpenGL framebuffers
Syntax:void SwapBuffers();
ToggleFullscreen - Toggle between fullscreen and windowed mode
Syntax:void ToggleFullscreen();
SetParentWindow - Set parent window handle
Syntax:void SetParentWindow(HWND hWndParent);
GetParentWindow - Return parent window handle
Syntax:HWND GetParentWindow() const;
GetWindowHandle - Return window handle
Syntax:HWND GetWindowHandle() const;
GetResolution - Return resolution window was created with
Syntax:void GetResolution(int& nWidth, int& nHeight, int& nColorDepth) const;
GetWidth - Return current window width (pixel)
Syntax:int GetWidth() const;
GetHeight - Return current window height (pixel)
Syntax:int GetHeight() const;
GetColorDepth - Return current window color depth (bits per pixel)
Syntax:int GetColorDepth() const;
IsCreated - Check if window is created
Syntax:bool IsCreated() const;
IsVisible - Check if window is visible
Syntax:bool IsVisible() const;
IsFullScreen - Check if window is fullscreen
Syntax:bool IsFullScreen() const;
StoreModes - Store or restore OpenGL modes
Syntax:static void StoreModes(OpenGlModes* pModes, bool bStore = true);
static void RestoreModes(OpenGlModes* pModes);

2.17. IObjectInterface

Description: Interface for managed data objects
Header file: SharkVisualisation_Classes.h, namespace SharkVisualisation
Load - Load object into memory
Syntax:virtual bool Load(const char* szFileName, SharkEngine::CFileStream& file, GLfloat fMinfilter, GLfloat fMaxfilter, CBaseController* pController) = 0;
Unload - Unload object and release used resources
Syntax:virtual void Unload() = 0;
GetComponent - Return visualisation component
Syntax:virtual int GetComponent() const = 0;
IsLoaded - Check if object is loaded
Syntax:virtual bool IsLoaded() const = 0;

2.18. Misc

Description: Miscellaneous helper methods
Header file: SharkVisualisation_Definitions.h, namespace SharkVisualisation
GetLibraryVersion - Return library version of SharkVisualisation
Syntax:const char* GetLibraryVersion();
For further information and feedback please contact me.
Pichat is a simple to use peer to peer (P2P) chat software. It comes with integrated webchat, web server and chat server. The chat supports multiple chatrooms, text formatting with smileys and a user-friendly webchat (HTML, CSS, DOM, JavaScript). The webchat works with nearly any web browser, easily integrated into your design, no PHP/Flash/Java required. Software for free information exchange for Linux and Windows.