00001 /*! \file 00002 \author victorien ferry & www.m4nkind.com 00003 \brief This file applies the GNU LESSER GENERAL PUBLIC LICENSE Version 2.1 , read file COPYING. 00004 */ 00005 #ifndef COM_M4NKIND_VirtualMachine_H 00006 #define COM_M4NKIND_VirtualMachine_H 00007 00008 /*! 00009 \addtogroup VirtualMachineDocGroup VirtualMachine Related Documentations 00010 \brief Here are links to documentations related to VirtualMachine. 00011 It is a pure virtual class for hardware abstraction provided in the base library. 00012 Here, You can also access to the different groups of methods of 00013 that class by theme, and possible inherited implementations ! 00014 In each Machine project directory, you should find a version of 00015 VedaDefaultMachine.h , which typedefs a VedaDefaultMachine class to the 00016 default Machine class. 00017 Note VirtualMachine is completely independant from other APIs and includes, 00018 so this documentations will also keep independants. 00019 */ 00020 /*! 00021 \class VirtualMachine 00022 \ingroup VirtualMachineDocGroup 00023 \author victorien -dot- ferry at free -dot- fr, with the mankind demo group team: www.m4nkind.com 00024 \brief Pure Virtual class for all machine specific methods. 00025 These methods should be completed for each machines in separate inherited libraries. 00026 This class will keep 100% independant from any other classes or API. 00027 This should be possible to only use a VirtualMachine for a whole program, 00028 to reach hardware abstraction.<br> 00029 Methods documentation has been grouped by theme: 00030 - the \ref InitMethods "Init Methods" 00031 - the \ref Render3D "3D Render Nested Classes and Methods" 00032 - the \ref MachineSound "Sound Methods" 00033 - the \ref MachineCultural "Cultural Configuration Methods" 00034 - the \ref MachineInterface "Interface Methods" 00035 - the \ref MachineDOS "Disk Operating and System Methods" 00036 */ 00037 00038 class VirtualMachine 00039 { 00040 /*================================================================== 00041 PUBLIC 00042 ==================================================================*/ 00043 public: 00044 /*! \addtogroup InitMethods VirtualMachine Init Methods 00045 \ingroup VirtualMachineDocGroup 00046 \brief Init Methods for VirtualMachine 00047 \{ 00048 */ 00049 /*! 00050 \brief Constructor. There should only be members initialisation there. 00051 */ 00052 VirtualMachine(void); 00053 #ifdef _ENGINE_EDITABLE_ 00054 /*! 00055 \brief Destructor. 00056 */ 00057 virtual ~VirtualMachine(void); 00058 #endif 00059 /*! 00060 \typedef eVMResult 00061 \brief error enum for InitMachine() 00062 */ 00063 typedef enum { 00064 //! init OK 00065 vmr_OK=0, 00066 //! init failed 00067 vmr_FAILED 00068 } eVMResult; 00069 /*! 00070 \brief Init the machine. It would open a screen and do the init for each theme (3D,sound,...) 00071 Then, the Main Screen stands as the ViewPort GetDefaultViewPort() . 00072 the machine closing should be done at deletion. 00073 \return vmr_OK or vmr_FAILED 00074 */ 00075 virtual eVMResult InitMachine()=0; 00076 //! \} 00077 /*================================================================== 00078 3D Render Model. 00079 ==================================================================*/ 00080 /*! \addtogroup Render3D VirtualMachine 3D Render Methods 00081 \ingroup VirtualMachineDocGroup 00082 \brief Nested classes and methods for graphic rendering with a VirtualMachine. 00083 This is thought as short as possible, but with enough features 00084 to support a classic 3D rendering state of the art: It has multiple layer 00085 for textures (InternalTexture::SetImageBitmap() ), and 3D object compilation 00086 if an object got a static shape. ( InternalObject3DBuffer::CompileAsStatic() ) 00087 It is also planned to support virtual screens and rectangle hierarchy 00088 with nested class InternalViewPort. You draw 3D objects with InternalViewPort::RenderMesh(). 00089 */ 00090 /*! 00091 \class InternalVertex 00092 \ingroup Render3D 00093 \brief Nested class that defines a vertex for use with 00094 InternalObject3DBuffer::GetFirstVertex(). Note: this vertex definition 00095 should not change (no more member or virtual methods). 00096 It is sometimes used as a list element. 00097 */ 00098 class InternalVertex 00099 { public: 00100 //! the vertex position. Always enabled. 00101 float m_x,m_y,m_z; 00102 //! the vertex normal, norm must be 1.0. 00103 float m_nx,m_ny,m_nz; 00104 //! the 2D texture coordinates if there are: 00105 float m_u,m_v; 00106 //! the color/alpha transluency of the vertex. 00107 float m_ColorRGBA[4]; 00108 /*! 00109 \brief Set the x,y,z position of the vertex. 00110 */ 00111 inline void SetPosition( float _x,float _y, float _z ){ m_x = _x; m_y = _y; m_z = _z ; }; 00112 /*! 00113 \brief Set the UV coordinate for texture mapping for the vertex. 00114 */ 00115 inline void SetUV( float _u,float _v){ m_u = _u; m_v = _v;}; 00116 /*! 00117 \brief set in the same time position of the vertex, and also apply to the UV texture coordinates. 00118 */ 00119 inline void SetPositionUV( float _x,float _y, float _z ) 00120 { m_x = m_u = _x; m_v = m_y = _y; m_z = _z ; }; 00121 /*! 00122 \brief set Normal Vector for this vertex. It must be normalized. 00123 */ 00124 inline void SetNormalVector( float _x,float _y, float _z ){ m_nx = _x; m_ny = _y; m_nz = _z ; }; 00125 }; 00126 /*! 00127 \class InternalTriangle 00128 \ingroup Render3D 00129 \brief Nested class that defines a Triangle Polygon for use with 00130 InternalObject3DBuffer::GetFirstTriangle(). Note: this triangle definition 00131 should not change (no more member or virtual methods).sizeof(InternalTriangle) 00132 must always be 12 because it is sometimes used as a list element. 00133 */ 00134 class InternalTriangle 00135 { public: 00136 //! the indexes of the polygon. 00137 unsigned int m_p0,m_p1,m_p2; 00138 }; 00139 /*! 00140 \class InternalObject3DBuffer 00141 \ingroup Render3D 00142 \brief Nested class to define a 3D object as a vertex and a polygon list. 00143 You ask the creation of it with VirtualMachine::NewObject3DBuffer(), 00144 then defines its shape by filling the list you get with GetFirstVertex() 00145 and GetFirstTriangle(), then it can be rendered with RenderMesh(). 00146 In order to optimize a static shape, use CompileAsStatic() 00147 In edition mode, it can be destroyed with VirtualMachine::DeleteObject3DBuffer(). 00148 */ 00149 class InternalObject3DBuffer 00150 { public: 00151 /*! 00152 \brief Get the beginning of the vertex list. Assume the maximum number of vertex 00153 was given by NewObject3DBuffer() and can be read with GetMaximumNumberOfVertexes(). 00154 \return a pointer to the first Vertex. 00155 */ 00156 virtual InternalVertex *GetFirstVertex()=0; 00157 /*! 00158 \brief Get the beginning of the Triangle list. Assume the maximum number of Triangle 00159 was given by NewObject3DBuffer() and can be read with GetMaximumNumberOfTriangles(). 00160 last Note: the first triangle returned already use the offset given with SetNumberOfActiveTriangle(): _FirstActiveTriangleIndex. 00161 \return a pointer to the first Vertex. 00162 */ 00163 virtual InternalTriangle *GetFirstTriangle()=0; 00164 /*! 00165 \brief Set the number of active triangle defined in the triangle list. 00166 note the active number of vertex is actually given by the highest vertex 00167 number used by one of the active triangle. If _CurrentNumberOfTriangle is 00168 greater than GetMaximumNumberOfTriangles(), it is set to zero. 00169 _FirstActiveTriangleIndex is an optional offset in the triangle list. 00170 it allows the rendering of a mesh with multiple textures, by 00171 setting a windowing in the triangle list and using 00172 multiple calls to RenderMesh(). Default is zero, start of the list. 00173 \param _CurrentNumberOfTriangle the new number of triangle in the object. 00174 \param _FirstActiveTriangleIndex optional active triangle offset in list. 00175 */ 00176 virtual void SetNumberOfActiveTriangle( unsigned int _CurrentNumberOfTriangle,unsigned int _FirstActiveTriangleIndex=0 )=0; 00177 /*! 00178 \brief Get the number of active triangle defined by SetNumberOfActiveTriangle(). 00179 \return the number of triangle in the object. 00180 */ 00181 virtual unsigned int GetNumberOfActiveTriangle()=0; 00182 /*! 00183 \brief the maximum number of elements in table GetFirstVertex() 00184 \return the maximum number of elements in table GetFirstVertex() 00185 */ 00186 virtual unsigned int GetMaximumNumberOfVertexes()=0; 00187 /*! 00188 \brief the maximum number of elements in table GetFirstTriangle() 00189 \return the maximum number of elements in table GetFirstTriangle() 00190 */ 00191 virtual unsigned int GetMaximumNumberOfTriangles()=0; 00192 /*! 00193 \brief Set the color for the whole object. Active if object was not created with bOb3D_EnableRGBA. 00194 \param _red color component 00195 \param _green color component 00196 \param _blue color component 00197 \param _alpha color component 00198 */ 00199 virtual void SetColor(float _red,float _green,float _blue,float _alpha=1.0f)=0; 00200 /*! 00201 \brief A call to CompileAsStatic() will fix the current geometry of an object. 00202 It will try to use the 3D buffer compilation of a given machine, which can fasten the drawing. 00203 From that moment on, further modification to its shape will be useless. 00204 */ 00205 virtual void CompileAsStatic()=0; 00206 /*! 00207 \brief return true is CompileAsStatic() were used. 00208 \return true is CompileAsStatic() were used, false if still dynamic. 00209 */ 00210 virtual bool IsCompiledAsStatic()=0; 00211 }; 00212 /*! 00213 \class InternalTexture 00214 \ingroup Render3D 00215 \brief Nested class that defines a texture to render an object with VirtualMachine::RenderMesh(). 00216 */ 00217 class InternalTexture 00218 { public: 00219 //! \brief InternalTexture::SetRenderFlags() enum. 00220 typedef enum { 00221 //! Bilinear filtering 00222 itf_Filtered=1 00223 //! drawing will be additive over previous drawings. 00224 ,itf_Additive=2 00225 //! the environment layer will be additive over the mapping/color layer. 00226 ,itf_envAdd=4 00227 //! texture bitmap horizontal clamping. 00228 ,itf_ClampTxtU=8 00229 //! texture bitmap vertical clamping. 00230 ,itf_ClampTxtV=16 00231 //! drawing writes the depth buffer. 00232 ,itf_depthwrite=32 00233 //! drawing test the depth buffer. 00234 ,itf_depthtest=64 00235 //! drawing will be substractive over previous drawings. 00236 ,itf_substractive=128 // very rare bits should start at bit 7 for better compression with PackULong_Flags. 00237 //! back faces are also drawn. 00238 ,itf_doublesided=256 00239 } InternalTextureFlagBitsEnum; 00240 /*! 00241 \brief Set or change the render flags for a texture. 00242 \param _flags or'ed bit flags ( InternalTextureFlagBitsEnum) 00243 */ 00244 virtual void SetRenderFlags( unsigned int _flags )=0; 00245 /*! 00246 \brief Set base color, default to 1.0f,1.0f,1.0f,1.0f 00247 \param _rgba Red Green Blue and Alpha transparency components. 00248 */ 00249 virtual void SetBaseColor( float _rgba[4] )=0; 00250 /*! 00251 \brief Get the render flags for a texture. 00252 \return or'ed bit flags (InternalTextureFlagBitsEnum) 00253 */ 00254 virtual unsigned int GetRenderFlags( )=0; 00255 //! \typedef TextureImageLayerEnum 00256 //! \brief InternalTexture image layer enum to use with SetImageBitmap() 00257 typedef enum { 00258 //! for texture mapping layer 00259 itile_TextureMapping=0, 00260 //! for environment layer 00261 itile_Environment 00262 } TextureImageLayerEnum; 00263 /*! 00264 \brief set an image layer for a texture. see layers with a TextureImageLayerEnum enums. 00265 \param _layerToSet the enum that define which layer to change. 00266 \param _pByteChunk pointer to a byte chunk. each pixels are _pixelByteDepth width. 00267 \param _pixelByteDepth number of bytes per pixel in _pByteChunk. 00268 \param _pixelWidth the number of pixel in a row 00269 \param _pixelHeight the number of pixel lines. 00270 */ 00271 virtual void SetImageBitmap( TextureImageLayerEnum _layerToSet, 00272 const unsigned char *_pByteChunk, 00273 unsigned int _pixelByteDepth, 00274 unsigned int _pixelWidth, 00275 unsigned int _pixelHeight 00276 )=0; 00277 }; 00278 /*! 00279 \class InternalViewPort 00280 \ingroup Render3D 00281 \brief Nested class that defines a viewport where to draw (screen, sub-screen,texture rendering screens.) 00282 This is a virtual class. Construction must be done by NewViewPortChild(), 00283 NewViewPortOnTexture() or InitMachine() for the default viewport accessible with 00284 VirtualMachine::GetDefaultViewPort() which stands for the main screen. 00285 */ 00286 class InternalViewPort 00287 { public: 00288 /*! 00289 \brief Reset color to black (or given color),and depth buffer, of this ViewPort. 00290 \param _red [0.0,1.0] 00291 \param _green [0.0,1.0] 00292 \param _blue [0.0,1.0] 00293 */ 00294 virtual void Clear( float _red=0.0f,float _green=0.0f,float _blue=0.0f)=0; 00295 /*! 00296 \brief Render a 3D Object. The vertexes are transformed with a matrix you set with matrix methods 00297 Matrix_LoadID() , Matrix_Translate() , Matrix_Rotate() , Matrix_Scale() , Matrix_Push() , Matrix_Pop() 00298 the object shape is defined by _pMeshBuffer, the texture of the object is 00299 defined by _pTexture. 00300 Note drawings on the main screen needs a SwapBuffer() to be shown at each frames. 00301 \param _pMeshBuffer InternalObject3DBuffer 00302 \param _pTexture InternalTexture or null, it will shade vertex color. 00303 */ 00304 virtual void RenderMesh( 00305 InternalObject3DBuffer *_pMeshBuffer, 00306 InternalTexture *_pTexture=0L 00307 ) =0 ; 00308 /*! 00309 \brief Render directly a 32bit pixel bitmap image from memory on the whole viewport. 00310 note Position Coordinates are not used. the bitamp is just scaled to the viewport. 00311 Note drawings on the main screen needs a SwapBuffer() to be shown at each frames. 00312 00313 \param _prgbaTable pointer to the beginning of a 32bit RGBA table. 00314 \param _PixelWidth number of pixel of a line 00315 \param _PixelHeight number of pixel lines. 00316 */ 00317 virtual void DrawRGBARectangle( 00318 unsigned char *_prgbaTable, 00319 unsigned int _PixelWidth, 00320 unsigned int _PixelHeight 00321 ) =0 ; 00322 00323 /*! 00324 \brief Swap buffers so that what was drawn on the viewport is shown. 00325 this is needed to active all Clear(), RenderMesh() ,... 00326 */ 00327 virtual void SwapBuffer()=0; 00328 /*! 00329 \brief manage 3D projection FOV 00330 */ 00331 inline void SetFOVLength( float _fovlength ){ m_fov = _fovlength; }; 00332 /*! 00333 \brief manage 3D projection near cut plane distance. 00334 */ 00335 inline void SetNearCutPlane( float _neardistance ){ m_NearCutPlane = _neardistance; }; 00336 /*! 00337 \brief manage 3D projection far cut plane. 00338 */ 00339 inline void SetFarCutPlane( float _fardistance ){ m_FarCutPlane = _fardistance; }; 00340 00341 /* 00342 \brief Change the coodinates of the clipping borders of a ViewPort, 00343 in the origin of its father.default is 0.0,0.0,1.0,1.0 00344 If the ViewPort is a Root ViewPort, like the main screen, 00345 or a texture rendering, it is inactive. 00346 \param _ClippingX1 upperleft corner in [0,1] scale for visible bounds. 00347 \param _ClippingY1 upperleft corner in [0,1] scale for visible bounds. 00348 \param _ClippingX2 downright corner in [0,1] scale for visible bounds. 00349 \param _ClippingY2 downright corner in [0,1] scale for visible bounds. 00350 */ 00351 virtual void SetClippingCoordinates(float _ClippingX1,float _ClippingY1,float _ClippingX2,float _ClippingY2 )=0; 00352 /* 00353 \brief Change the coodinates of the draw scale of a ViewPort, in the origin 00354 of its father. default is 0.0,0.0,1.0,1.0 00355 If the ViewPort is a Root ViewPort, like the main screen, 00356 or a texture rendering, it is inactive. 00357 Note again, the coordinates given are in the father viewport origin. 00358 00359 \param _ScaleX1 upperleft corner in [0,1] scale for aspect ratio . 00360 \param _ScaleY1 upperleft corner in [0,1] scale for aspect ratio . 00361 \param _ScaleX2 downright corner in [0,1] scale for aspect ratio . 00362 \param _ScaleY2 downright corner in [0,1] scale for aspect ratio . 00363 */ 00364 virtual void SetScaleCoordinates(float _ScaleX1,float _ScaleY1,float _ScaleX2,float _ScaleY2 )=0; 00365 00366 /*! 00367 \brief Get upperleft horizontal the coordinate of this ViewPort, in the father's origin. 00368 \return coord in [0,1] scale. 00369 */ 00370 inline float GetPositionX1(){ return m_ScaleX1; }; 00371 /*! 00372 \brief Get the upperleft vertical coordinate of this ViewPort, in the father's origin. 00373 \return coord in [0,1] scale. 00374 */ 00375 inline float GetPositionY1(){ return m_ScaleY1; }; 00376 /*! 00377 \brief Get the downright horizontal coordinate of this ViewPort, in the father's origin. 00378 \return coord in [0,1] scale. 00379 */ 00380 inline float GetPositionX2(){ return m_ScaleX2; }; 00381 /*! 00382 \brief Get the downright vertical coordinate of this ViewPort, in the father's origin. 00383 \return coord in [0,1] scale. 00384 */ 00385 inline float GetPositionY2(){ return m_ScaleY2; }; 00386 /*! 00387 \brief Get upperleft horizontal the coordinate of this ViewPort. 00388 \return coord in [0,1] scale. 00389 */ 00390 inline float GetClippingX1(){ return m_ClippingX1; }; 00391 /*! 00392 \brief Get the upperleft vertical coordinate of this ViewPort. 00393 \return coord in [0,1] scale. 00394 */ 00395 inline float GetClippingY1(){ return m_ClippingY1; }; 00396 /*! 00397 \brief Get the downright horizontal coordinate of this ViewPort. 00398 \return coord in [0,1] scale. 00399 */ 00400 inline float GetClippingX2(){ return m_ClippingX2; }; 00401 /*! 00402 \brief Get the downright vertical coordinate of this ViewPort. 00403 \return coord in [0,1] scale. 00404 */ 00405 inline float GetClippingY2(){ return m_ClippingY2; }; 00406 /*! 00407 \brief the root viewport if it is a sub-viewport, or 'this' if root. 00408 \return the parent root viewport. 00409 */ 00410 inline InternalViewPort *GetRootViewPort(){ return m_pRootViewPort; }; 00411 /*! 00412 \brief Get the direct father viewport, or 0L if Root. 00413 \return the father InternalViewPort or 0L. 00414 */ 00415 inline InternalViewPort *GetFatherViewPort(){ return m_pClippingFatherViewPort; }; 00416 /*! 00417 \typedef eLoadId 00418 \brief Matrix_LoadID() special enum 00419 */ 00420 typedef enum { 00421 //! all matrix terms are set to ID 00422 eLoadId_All=0, 00423 //! only rotation terms (3x3) are set to ID. 00424 eLoadId_Rotation 00425 } eLoadId ; 00426 /*! 00427 \brief The matrix becomes an Identity matrix, which means no transformation at all. 00428 It cleans all previous transformations. 00429 _enum can be used to only affect the rotation terms (3x3 matrix) 00430 \param _enum 00431 */ 00432 virtual void Matrix_LoadID(eLoadId _enum=eLoadId_All)=0; 00433 /*! 00434 \brief Add a translation transformation to the matrix. 00435 \param _x x axis distance to move. 00436 \param _y y axis distance to move. 00437 \param _z z axis distance to move. 00438 */ 00439 virtual void Matrix_Translate(float _x,float _y,float _z)=0; 00440 /*! 00441 \brief Add a Rotation to the matrix, using a quaternion. 00442 \param _angleRad an angle given in radian. 00443 \param _x x normalized axis to rotate. 00444 \param _y y normalized axis to rotate. 00445 \param _z z normalized axis to rotate. 00446 */ 00447 virtual void Matrix_Rotate( float _angleRad,float _x,float _y,float _z)=0; 00448 /*! 00449 \brief Add a Scale to the matrix. 00450 \param _x Rate to scale the X axis. 00451 \param _y Rate to scale the Y axis. 00452 \param _z Rate to scale the Z axis. 00453 */ 00454 virtual void Matrix_Scale(float _sx,float _sy,float _sz)=0; 00455 /*! 00456 \brief Push the current state of the matrix in the stack. 00457 */ 00458 virtual void Matrix_Push()=0; 00459 /*! 00460 \brief Pop the last state of the matrix from the stack. 00461 */ 00462 virtual void Matrix_Pop()=0; 00463 protected: 00464 //! 2d coordinates of the rectangle scale, in [0,1] values, in the father position scale. 00465 float m_ScaleX1; 00466 float m_ScaleY1; 00467 float m_ScaleX2; 00468 float m_ScaleY2; 00469 //! 2d coordinates of the rectangle bounds, in [0,1] float scale values. 00470 float m_ClippingX1; 00471 float m_ClippingY1; 00472 float m_ClippingX2; 00473 float m_ClippingY2; 00474 //! the root viewport if it is a sub-viewport, or 'this' if root. 00475 InternalViewPort *m_pRootViewPort; 00476 //! the father in the hierarchy of ViewPort 00477 InternalViewPort *m_pPositionFatherViewPort; 00478 //! the first son in the hierarchy of ViewPort. 00479 InternalViewPort *m_pPositionFirstSonViewPort; 00480 //! the next brother in the hierarchy of ViewPort. 00481 InternalViewPort *m_pPositionNextBrotherViewPort; 00482 //! the father in the hierarchy of ViewPort 00483 InternalViewPort *m_pClippingFatherViewPort; 00484 //! the first son in the hierarchy of ViewPort. 00485 InternalViewPort *m_pClippingFirstSonViewPort; 00486 //! the next brother in the hierarchy of ViewPort. 00487 InternalViewPort *m_pClippingNextBrotherViewPort; 00488 //! for 3D rendering, Distance between the projected plane and the center. must be >0.001 00489 float m_fov; 00490 //! for 3D rendering,Near cut plane, must be >0.001 and <= FarCutPlane 00491 float m_NearCutPlane; 00492 //! for 3D rendering,Far cut plane, must be >= NearCutPlane 00493 float m_FarCutPlane; 00494 00495 }; 00496 /*! 00497 \typedef InternalObject3DBuffer_InitBit 00498 \ingroup Render3D 00499 \brief see VirtualMachine::NewObject3DBuffer() 00500 */ 00501 typedef enum { 00502 //! Flag bit for NewObject3DBuffer(). Needed to enable InternalVertex::m_nx,m_ny,m_nz, for environment mapping and lightning. 00503 bOb3D_VertexNormal=1, 00504 //! Flag bit for NewObject3DBuffer(). Needed to enable InternalVertex::m_u,m_v. 00505 bOb3D_VertexUVMapping=2, 00506 //! Flag bit for NewObject3DBuffer(). Needed to enable InternalVertex::m_ColorRGBA 00507 bOb3D_VertexRGBA=4 00508 } InternalObject3DBuffer_InitBit ; 00509 00510 /*! 00511 \ingroup Render3D 00512 \brief Ask the Creation of a new InternalObject3DBuffer you can then fill with 00513 InternalObject3DBuffer::GetFirstVertex() , InternalObject3DBuffer::GetFirstTriangle(). 00514 Important: All the vertex members and polygon index are inited to zero when built. 00515 and InternalObject3DBuffer::SetNumberOfActiveTriangle() . 00516 Then the object can be positionned with the matrix methods in VirtualMachine::InternalViewPort, and drawn with VirtualMachine::InternalViewPort::RenderMesh(). 00517 The object shape can be dynamic and rebuilt, until a call to VirtualMachine::InternalObject3DBuffer::CompileAsStatic(). 00518 In edition compilation mode, objects had to be destroyed with VirtualMachine::DeleteObject3DBuffer(). 00519 \param _ppVertexAndPolygonBufferOut the object returned, or 0L if failed.(no mem ?) 00520 \param _maxNbVertex maximum number of vertex to fill. 00521 \param _maxNbTriangle maximum number of Triangle to fill. 00522 \param _extraMemberFlags or'ed bits (bOb3D_...) to activate extra vertex members. 00523 */ 00524 virtual void NewObject3DBuffer( InternalObject3DBuffer **_ppVertexAndPolygonBufferOut, 00525 unsigned int _maxNbVertex, 00526 unsigned int _maxNbTriangle, 00527 unsigned int _extraMemberFlags )=0; 00528 00529 /*! 00530 \ingroup Render3D 00531 \brief Destroy objects previously created with NewObject3DBuffer() 00532 \param _ppBufferToDestroy object to destroy, and set to 0L. 00533 */ 00534 virtual void DeleteObject3DBuffer( InternalObject3DBuffer **_ppBufferToDestroy )=0; 00535 00536 /*! 00537 \brief Ask the Creation of a new InternalTexture, then used to render 3D objects with RenderMesh(). 00538 In edition mode, InternalTexture has to be destroyed with DeleteTexture(). 00539 \param _ppTextureOut the object returned, or 0L if failed.(no mem ?) 00540 */ 00541 virtual void NewTexture( InternalTexture **_ppTextureOut )=0; 00542 00543 #ifdef _ENGINE_EDITABLE_ 00544 /*! 00545 \ingroup Render3D 00546 \brief Destroy objects previously created with NewTexture() 00547 \param _ppTextureToDestroy object to destroy, and set to 0L. 00548 */ 00549 virtual void DeleteTexture( InternalTexture **_ppTextureToDestroy )=0; 00550 #endif 00551 00552 /*! 00553 \ingroup Render3D 00554 \brief Ask the Creation of a new InternalViewPort, that must be the child of another ViewPort, 00555 specified by _pFatherViewPort.if no father is specified, the new ViewPort will be 00556 the child of the default root ViewPort. To create another Root ViewPort, create a texture 00557 and use VirtualMedia::NewViewPortOnTexture(). 00558 In edition mode, each InternalViewPort has to be destroyed with DeleteViewPort(). 00559 \param _ppViewPortOut the object returned, or 0L if failed.(no mem ?) 00560 \param _pFatherViewPort the father viewport. If 0L, it uses the default root. 00561 */ 00562 virtual void NewViewPortChild( InternalViewPort **_ppViewPortOut,InternalViewPort *_pFatherViewPort=0L)=0; 00563 /*! 00564 \ingroup Render3D 00565 \brief Ask the Creation of a new Root InternalViewPort, that will render on a texture image. 00566 specified by _pRootTexture. You got to create a texture first for parameter _pRootTexture. 00567 In edition mode, each InternalViewPort has to be destroyed with DeleteViewPort(). 00568 \param _ppViewPortOut the object returned, or 0L if failed.(no mem ?) 00569 \param _pRootTexture an InternalTexture. Can't be null. 00570 \param _np2PixelWidth integer which can be 1,2,4,8,16,32,64,128,256,512 that stand for the square of the pixel width. 00571 \param _np2PixelHeight integer which can be 1,2,4,8,16,32,64,128,256,512 that stand for the square of the pixel height. 00572 \param _layerToAffect the texture layer (simple mapping, environment) where to render. 00573 */ 00574 virtual void NewViewPortOnTexture( InternalViewPort **_ppViewPortOut, 00575 InternalTexture *_pRootTexture, 00576 unsigned int _np2PixelWidth, 00577 unsigned int _np2PixelHeight, 00578 InternalTexture::TextureImageLayerEnum _layerToAffect)=0; 00579 00580 /*! 00581 \ingroup Render3D 00582 \brief Destroy any objects previously created with NewViewPortChild() or NewViewPortOnTexture(). 00583 If it has children, children are detached , not destoyed, but are invalid. 00584 \param _ppViewPortToDestroy pointer to object to destroy, and set to 0L. 00585 */ 00586 virtual void DeleteViewPort( InternalViewPort **_ppViewPortToDestroy )=0; 00587 00588 /*! 00589 \ingroup Render3D 00590 \brief Access to the default screen object created with InitMachine(). 00591 \return the Viewport that stands for the whole screen, or NULL if not opened. 00592 */ 00593 inline InternalViewPort *GetDefaultViewPort(){ return m_pDefaultViewPort; }; 00594 00595 00596 /*================================================================== 00597 Sound Stuff 00598 ==================================================================*/ 00599 /*! 00600 \addtogroup MachineSound VirtualMachine Sound Methods 00601 \ingroup VirtualMachineDocGroup 00602 \brief Sound Classes and Methods for VirtualMachine. We use 00603 a very special way to support sound streams: 00604 We provide SoundInterface, a pure virtual class. You just got to extend 00605 it to another class and implement ProcessSoundInterupt() yourself. 00606 Then you must register an instance of it to the machine 00607 with EnableMediaSound(). as soon as it is registered, the machine 00608 will send your ProcessSoundInterupt(), which ask to <b>* add *</b> a 00609 stereo signal to a float sound stream described with class SoundBufferToAddYourSignal. 00610 And your signal will be instantly heard. To stop it, call EnableMediaSound() with false. 00611 Of course, the sound interupt is managed privately by the machine. 00612 Look this \ref Example_MinimalMedia "Minimal Example". 00613 \{ 00614 */ 00615 /*! 00616 \class SoundBufferToAddYourSignal 00617 \brief Defines the sound buffer to be mixed by SoundInterface::ProcessSoundInterupt() 00618 */ 00619 class SoundBufferToAddYourSignal 00620 { public: 00621 /*! Pointer to the float buffer where to add your signal on. 00622 it is a left+right stereo buffer with m_LengthToRender length.*/ 00623 float *m_pSoundBuffer; 00624 //! number of 2xfloat to add on m_pSoundBuffer. 00625 unsigned int m_LengthToRender; 00626 //! the constant frequency play in Herz(22050,44100,...) 00627 float m_PlayFrequency; 00628 /*! Time lapse of the buffer to mix, in seconds.( A given machine decide of the way calls are timed. ) 00629 Time values should be close to the date passed to ProcessMedia(), and should look like an accumulation: 00630 on 2 consecutive calls, End of last call == beginning of next call */ 00631 int m_StartPlayTime_SecondUnit; 00632 //! m_StartPlayTime_SecondUnit 's after the point values. 00633 unsigned int m_StartPlayTime_SecondFrac; 00634 //! time value at the end of the buffer, cf m_StartPlayTime_SecondUnit . 00635 int m_EndPlayTime_SecondUnit; 00636 //! m_StartPlayTime_SecondUnit 's after the point values. 00637 unsigned int m_EndPlayTime_SecondFrac; 00638 //! a multiplier for the volume, you should use. 1.0f By default. 00639 float m_MainVolume; 00640 }; 00641 /*! 00642 \class SoundInterface 00643 \brief Virtual base class for any kind of object that need to generate 00644 a sound signal. You have to extend it and implement ProcessSoundInterupt(). 00645 (see exemple in VirtualMedia.cpp) 00646 For more informations, look VirtualMachine::EnableMediaSound() 00647 */ 00648 class SoundInterface 00649 { public: 00650 /*! 00651 \brief Method thrown by the VirtualMachine to an object that must add a sound signal 00652 that will then be played As soon as possible. 00653 For more informations, look VirtualMachine::EnableMediaSound() 00654 \param _SoundBufferToAddYourSignal description of the buffer to mix on. 00655 */ 00656 virtual void ProcessSoundInterupt( VirtualMachine::SoundBufferToAddYourSignal &_SoundBufferToAddYourSignal )=0; 00657 00658 }; 00659 /*! 00660 \brief Return the machine main play frequency, in herz, (tick per sec). 00661 \return freq (44100.0,22050.0,...) 00662 */ 00663 virtual float GetPlayFrequency()=0; 00664 00665 /*! 00666 \brief Register a SoundInterface object that will then generate a mixed sound through 00667 SoundInterface::ProcessSoundInterupt(). The sound will start instantly. 00668 if false, Unregister a media object previously registered 00669 with EnableMediaSound(,true). The sound stops instantly. 00670 Note, that if you choose to use the BaseObject 00671 implementation, class VirtualMedia will manage the sound 00672 in its own way, and you will not need to use this method. 00673 \param _pNoisyObject the object that can generate noise. 00674 \param _enable true if you want to enable, false to disable. 00675 */ 00676 virtual void EnableMediaSound( SoundInterface *_pNoisyObject, bool _enable=true ); 00677 /*! 00678 \brief force a date to the clock passed to the sound objects. 00679 \param _seconds in second units. 00680 \param _fraction the following after-the-point-units of _seconds, like if the whole were a 64 bits integer. 00681 */ 00682 virtual void SetSoundCurrentTime(int _seconds,unsigned int _fraction )=0; 00683 /*! 00684 \brief tool: change main volume [0,1]. 00685 Yes, you can saturate when >1. 00686 \param _newVolumeValue [0,1] 00687 */ 00688 virtual void SetSoundVolume(float _newVolumeValue)=0; 00689 /*! 00690 \brief tool: get main volume value [0,1]. 00691 \return VolumeValue [0,1] 00692 */ 00693 virtual float GetSoundVolume()=0; 00694 /*! 00695 \brief return an image of the current short sound buffer which is currently played. 00696 This is always a 2 float(stereo left,right) table. 00697 the play frequency of this sound signal is given by GetPlayFrequency() . 00698 The buffer size may vary in time and implementation, and this table is refresh on an undefined rate. 00699 It can be used by sound preview methods or live effects. 00700 \param _ppSoundBuffer pointer on pointer on the buffer to return. 00701 \param _pLength pointer on a unsigned int that return the length. 00702 */ 00703 virtual void GetCurrentSoundBufferImage(float ** const _ppSoundBuffer,unsigned int *_pLength) const =0 ; 00704 00705 #ifdef _ENGINE_EDITABLE_ 00706 /*! 00707 \brief Now, AzurVeda virtual machine implements a very efficient 00708 BASS technology known as "ShutTheFuckUp" ! 00709 Yes, it will unregister all sound objects to silent the machine. 00710 */ 00711 virtual void ShutTheFuckUp(); 00712 #endif 00713 //! \} 00714 /*================================================================== 00715 Cultural Stuff 00716 ==================================================================*/ 00717 /*! 00718 \addtogroup MachineCultural VirtualMachine Cultural Configuration Methods 00719 \ingroup VirtualMachineDocGroup 00720 \brief Cultural configuration methods for VirtualMachine. We support this 00721 for localization purposes. 00722 \{ 00723 */ 00724 /*! \typedef eMachineLocalization 00725 \brief This enum spots a cultural langage. returned by GetCurrentWorldLocalizationEnum() 00726 */ 00727 typedef enum{ 00728 //! means we just don't know which country the machine is for. 00729 eMachineLocalization_LocalisationNotImplemented=0, // means the machine just don't implement this info. 00730 //! english machine. 00731 eMachineLocalization_English, 00732 //! french machine. 00733 eMachineLocalization_French, 00734 //! Castellano machine. 00735 eMachineLocalization_SpanishCastellano, 00736 //! German machine ! 00737 eMachineLocalization_German, 00738 //! Italian machine. 00739 eMachineLocalization_Italian, 00740 //! Polish machine. 00741 eMachineLocalization_Polish, 00742 //! portuguguese machine 00743 eMachineLocalization_Portuguese 00744 } eMachineLocalization; 00745 /*! 00746 \brief Return the language of the machine, as a simple enum. It can be used 00747 to display one or the other langage. 00748 \return an enum integer. 00749 */ 00750 virtual eMachineLocalization GetCurrentWorldLocalizationEnum()=0; 00751 /*! \} */ 00752 00753 /*================================================================== 00754 Interface Stuff 00755 ==================================================================*/ 00756 /*! 00757 \addtogroup MachineInterface VirtualMachine Interface Methods 00758 \ingroup VirtualMachineDocGroup 00759 \brief Methods to check peripherals and other things for VirtualMachine. 00760 For the moment it just check a general way to exit. 00761 */ 00762 /*! 00763 \ingroup MachineInterface 00764 \brief Process the Machine's interface messages (mouse,keyboard,...), in the real time. 00765 Then methods like VirtualMachine::GetQuitMessage() are updated. 00766 */ 00767 virtual void ProcessInterface()=0; 00768 00769 /*! 00770 \ingroup MachineInterface 00771 \brief If true, means that the user want to quit: 00772 \return true to quit. 00773 */ 00774 inline bool GetQuitMessage(){ return m_QuitMessage; }; 00775 00776 /*================================================================== 00777 Disk Operating and System Stuff. 00778 ==================================================================*/ 00779 /* 00780 \brief After init,Set a general machine title, for example, to be displayed 00781 as a windows title. You can change the machine title at any time. 00782 \param _pMachineTitle const string to be displayed. 00783 */ 00784 virtual void SetMachineTitle(const char *_pMachineTitle); 00785 /*! 00786 \addtogroup MachineDOS VirtualMachine Disk Operating and System Methods 00787 \ingroup VirtualMachineDocGroup 00788 \brief Disk and system functions for VirtualMachine 00789 \{ 00790 */ 00791 #ifdef _ENGINE_EDITABLE_ 00792 /*! 00793 \brief In edition mode, ask a file path to a file requester. 00794 the string format should vary, but will be compatible with LoadFile() and SaveFile() 00795 \param _pDisplayString a string to inform to what's the file for. 00796 \param _pResultFileName the file path , returned. 00797 \param _nameMaxLength the maximum buffer size to write. 00798 \return true if _pDisplayString valid. 00799 */ 00800 virtual bool FileRequester(const char *_pDisplayString,char *_pResultFileName, unsigned int _nameMaxLength )=0; 00801 #endif 00802 #ifdef _ENGINE_EDITABLE_ 00803 /*! 00804 \brief <b>DEPRECATED for the moment: use class PackResource instead</b> 00805 load a file into a memory chunk. You can load all in one row, or stream. 00806 memory is to be deleted by the CALLER with operator: "delete [] pointer", for each 00807 succesfull call. return 0L if failed. 00808 \param _pFilePath the path of the file to load 00809 \param _FileStart an offset of where to start reading the file. 0 if all file. 00810 \param _LoadByteLength return the exact real length of what was read and returned, if OK. 00811 \param _maximumSizeLoad the maximum length to read 00812 \return the memory chunk, or 0L if failed. 00813 */ 00814 // virtual const char *LoadFile(const char *_pFilePath,unsigned int _FileStart,unsigned int &_LoadByteLength, unsigned int _maximumSizeLoad=0xffffffff)=0; 00815 #endif 00816 #ifdef _ENGINE_EDITABLE_ 00817 /*! 00818 \brief write a file from a memory chunk. You can save all in one row, or stream. 00819 \param _pFilePath the path of the file to write 00820 \param _chunkToWrite your memory chunk to save, as char *. 00821 \param _ChunkLength the length of _chunkToWrite 00822 \param _append if true, file is continued. if false, file is rewritten. default to false. 00823 \return true if OK, false if not. 00824 */ 00825 virtual bool SaveFile(const char *_pFilePath,const char *_chunkToWrite,unsigned int _ChunkLength,bool _append=false)=0; 00826 #endif 00827 #ifdef _ENGINE_EDITABLE_ 00828 /*! 00829 \brief in edition mode, redirection of machine task wait. 00830 \param _milliseconds time to wait. 00831 */ 00832 virtual void Sleep( unsigned int _milliseconds )=0; 00833 #endif 00834 /*! \} */ 00835 /*================================================================== 00836 PROTECTED 00837 ==================================================================*/ 00838 protected: 00839 //! this is the default viewport, it stands the whole screen by default. Used by GetDefaultViewPort(). 00840 InternalViewPort *m_pDefaultViewPort; 00841 00842 //! If true, means that the user want to quit. Updated by ProcessInterface(). 00843 bool m_QuitMessage; 00844 00845 //! nested class to manage update sound object list; 00846 class SoundUpdateListCell 00847 { public: 00848 SoundUpdateListCell *m_pNext; 00849 SoundInterface *m_pMediaObject; 00850 }; 00851 //! start of the chained list of the sound object update method: 00852 SoundUpdateListCell *m_pFirstSoundObject; 00853 }; 00854 #endif
/\/\ 4 N k ! N D
_______ _ __ ___ _____ ___ _ _ ____
___________ __//___ /________ |/ / ___________\_______/ \
/ _ _ \/ _ / _ / _/_/____/ _ __ /
/ / / / / / \ \/ / / \ \ /
\\___/___/___/ ¯ _____/_____/ ______\___/_____/\________\\
\________/_ ___ __ l____\ /elD!
http://www.m4nkind.com \____/