SharkVisualisation documentation, generated with mkdocument

Last update 31/Mar/2011 by Mark Seuffert
Overview:
1.       Introduction
2.1.    CBase3d
2.2.    CBaseController
2.3.    CBaseManager
2.4.    CFont
2.5.    CFontManager
2.6.    CImagePng
2.7.    CImageTga
2.8.    CInput
2.9.    CModel
2.10.  CModelManager
2.11.  CModelMs3d
2.12.  CTexture
2.13.  CTextureManager
2.14.  CTimer
2.15.  CWindow
2.16.  CWindowConsole
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. Fur further information see http://www.pichat.net

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 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 when main loop is starting
  • OnMainLoopStop() informs when main loop is stopping
  • OnCreateWindow() informs when window has been created
  • OnDestroyWindow() informs when window will be destroyed
  • OnAnimate() animate and update objects
  • OnRender() render objects
  • OnRenderOverlay() render objects on top
  • OnOutput() called for logging and debugging output
These public member variables exist:
m_pTimerhigh resolution timer for main loop (owned)
m_pWindowOpenGL window (owned)
m_pWindowConsoleconsole text output (owned)
m_pInputinput handling (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);
Constants
log actions:
LOG_NONEnone or invalid
LOG_NOTICEgeneric notice information
LOG_DEBUGgeneric debug information
LOG_ERRORgeneric error information
LOG_CUSTOMcustom actions, free for use
 
base components (bits):
COMPONENT_NONEno component
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);
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);
GetResolution - Return window resolution
Syntax:void GetResolution(int& nWidth, int& nHeight, int& nColorDepth) const;
SetIcon - Set window icon
Syntax:void SetIcon(HICON hIcon, BYTE* pMask = NULL, bool bBigIcon = false);
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;
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;
Output - Output text
Syntax:void Output(int nLogAction, const char* szText);
ShowConsole - Show or hide console
Syntax:void ShowConsole(bool bShow = true);
ToggleConsole - Toggle console
Syntax:void ToggleConsole();
SetDebugMode - Set debug mode
Syntax:void SetDebugMode(bool bDebugMode);
IsDebugMode - Return debug mode
Syntax:bool IsDebugMode() 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;
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)
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. 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.5. 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.6. 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
Construction
Syntax:CImagePng();
LoadFromMemory - Load and decode image into buffer
Syntax:bool LoadFromMemory(const BYTE* pBuffer, int nBufferSize, 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.7. 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* pBuffer, int nBufferSize);
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. 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.9. 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.10. 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.11. 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* pBuffer, int nBufferSize);
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.12. 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.13. 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.14. 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.15. 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);
GetResolution - Return resolution window was created with
Syntax:void GetResolution(int& nWidth, int& nHeight, int& nColorDepth) const;
SetIcon - Set window icon
Syntax:void SetIcon(HICON hIcon, BYTE* pMask = NULL, bool bBigIcon = false);
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;
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.16. CWindowConsole

Description: Console text output
Header file: SharkVisualisation_Classes.h, namespace SharkVisualisation
Construction
Syntax:CWindowConsole(CBaseController* pController);
Constants
CONSOLE_BUFFER_SIZE = 99, CONSOLE_BUFFER_MAXLINE = 120
Create - Create console
Syntax:bool Create();
Destroy - Destroy console
Syntax:void Destroy();
Clear - Clear console content
Syntax:void Clear();
Output - Write text to console
Syntax:void Output(const char* szText);
void Output(const char* szText, int nLogAction);
Show - Show or hide console
Syntax:void Show(bool bShow = true);
Toggle - Toggle console between visible and hidden
Syntax:void Toggle();
Render - Draw console on screen
Syntax:void Render(bool bIsOrthoScreen = false);
IsCreated - Return if console is created
Syntax:bool IsCreated() const;
IsVisible - Return if console is visible
Syntax:bool IsVisible() const;

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 LAN messenger and webchat. The chat server 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.