Fine Programming from Paris.
(c) May 2002
|
Fine Programming from Paris.
(c) May 2002
|
| PROGRAMMER'S REFERENCES - 1 Concepts | |||||||||
|
XYZpoint is a 3D point defined by 3 numbers x y z of type WORD. Center of Scene image is (0,0,0) |
||||||||
|
|
Point is a reference to an XYZpoint in a Facette. It means that the XYZpoint values are NOT in the facette. Facette is a polygon made of Points. The user is responsable of non-convexity, non complexity cause Woof3D assume that polygons are simples and non ambigous. Objet is 3D Object like those defined in Caligari or Vscape files (hierarchical, matrix, etc...). This structure exist in Woof3D for compatibility. Objets are made of Points & Facettes & XYZpoint& Objets and some internal datas. Objets can be loaded from files or created from scratch. Element is something that can be move inside the Scene. So Elements are used for Animations but Elements can also be moved directly with the fonction Woof3DSetElementPosition() Element 0 is the Scene itself and so contain all. Elements can be a full Objet or several contigous Objets or one part from an Objet Frame is the position of an Element at a t time (TimeFrame). Animation is a list of Frames that define an Element movement (animation Timeframes). Image is a (mainly only 24 bits) picture loaded from files or created from scratch. Texture is a part of an Image that can be use for texturing an entire object or facettes. It's mainly a kind of SubImage with DrawMode and some internal datas. Button is a button inside a Window. SubImage is a rectangular part of an Image that can be use for sprites or buttons. Return Value All WoofD functions return a WORD. Often it is the Number of the created or modified Thing. Often it is 0 for functions that never fail. But if it return a negative value the function have fail for sure It is safer to use the macro VERIFY(Number ) that is equivalent to if (Number < 0) goto ProgEnd; Exemple: Nscene=Woof3DOpenScene(AUTO,AUTO,Nwindow); Thing is a generic term for designing an Objet, an Image, a Texture, etc.. from this Scene. Nthing or Number is a WORD that give access to a Thing (an Objet, an Image, a Texture, etc....). So there are in fact Nobjet, Nimage, Nwindow,etc... So you never use pointers with Woof3D but numeric handles called Nthings Name is a string of char (UBYTE *name) for naming a Thing (Objet, Image, Texture, etc...) You can obtain the Number of a Thing (Objet, Image, Texture, etc...) with Woof3DGetNumber( ) FileName is a string of char (UBYTE *name) defining a path and file name. Example "..\images\dinosaure.bmp" |
||||||||
|
PROGRAMMER'S REFERENCES - 2 Functions |
|||||||||
|
WORD Woof3DAddAnimation (UBYTE * name ,WORD AnimMode ); Description Add a new empty animation to the Scene with given name. It will then need Woof3DAddFrameSpecial parameters AnimModeReturn value Nanimation
WORD Woof3DAddElement (UBYTE * name ,WORD Nobjet1 ,WORD Npoint1 ,WORD Nobjet2 ,WORD Npoint2 ); Description Add a new Element to the Scene. This Element is made from all the Objets/Facettes between Nobjet1/Nfacette1 and Nobjet2/NFacette2Special parameters Nfacette1 and Nobjet2/NFacette2 can be AUTO for selecting a single NObjet1Return value Nelement = Element added
WORD Woof3DAddFacette (void); Description Add an empty Facette to the last Objet of the SceneSpecial parameters Return value Nfacette= This Facette Number
WORD Woof3DAddFacetteFromFX(WORD *parameters,WORD FacetteFXMode); Description Create Facettes from existing PointsSpecial parameters Return value
WORD Woof3DAddImage (UBYTE * name ,WORD large ,WORD high ,WORD bits ); Description Create a new Image in the Scene for user use.Special parameters bits can be 8 15 16 24 32 bits. But most functions only works with 24 bits. (in v1.0 always use 24 bits)Return value Nimage= The new image number. Note that this image is not used by anything (Sys or Scene) and must be freeed by user.
WORD Woof3DAddObjet (UBYTE * name ); Description Add an empty Objet to the Scene.Special parameters Return value Nobjet = Objet created
WORD Woof3DAddObjetFromFX (WORD * parameters ,WORD ObjetFXMode ); Description Create an Objet from other Objets/Facettes with a special effects (FX) Usefull for creating Objet from scratchSpecial parameters ObjetFXModeReturn value Nobjet = Objet created
WORD Woof3DAddPointFacette (WORD Npoint ); Description Add the nth XYZPoint to the last Facette of the last Objet of the SceneSpecial parameters Return value Nfacette= last Facette Number
WORD Woof3DAddPointXYZ (WORD x ,WORD y ,WORD z ); Description Create one X Y Z point in the last objet. Similar to Woof3DAddPointXYZFromImage( ). Center of Scene image is (0,0,0)Special parameters Return value Npoint= Last point created number or return -1 if cant create more points.
WORD Woof3DAddPointXYZFromImage (WORD Nimage ,UBYTE * RGB ,WORD CenterMode ); Description Create automatically from an image a serie of X Y Z points in the last objet. Similar to Woof3DAddPointXYZ with X Y Z values that are the coordinates inside the image. If a pixel has the same color than *RGB then it is added to the list. Z is always 0. No facettes are created.Special parameters CenterMode define how the X Y Z points are centeredReturn value Number of X Y Z points created
WORD Woof3DAddSetFrame (WORD Nframe ,ULONG time ,WORD Nelement ,WORD RefMode ,WORD Xtheta ,WORD Ytheta ,WORD Ztheta ,LONG GlobalPosX ,LONG GlobalPosY ,LONG GlobalPosZ ); Description Add and Set a new frame to the Scene inside the last animation defined. or Set an existing frame.Special parameters NEW if n is set to NEW then add a new frame else modify an existing one.Return value Nframe
WORD Woof3DAddSubImage (WORD Nimage ,UBYTE * name ,WORD x ,WORD y ,WORD large ,WORD high ); Description Add a SubImageSpecial parameters Return value
WORD Woof3DAddTexture (WORD Nimage ,WORD x ,WORD y ,WORD large ,WORD high ,WORD posX ,WORD posY ,WORD TexMode ,WORD DrawMode ,UBYTE * name ); Description Create a Texture from given Image number n minX,minY,maxX,maxY specify the rectangle defining the texture area within this Image posX posY define the Texture Centering. DrawMode define the drawing method for Facette/PointsSpecial parameters minX,minY,maxX,maxY can be AUTO so Texture is Image size. posX posY can be AUTO so Texture is centered.Return value Ntexture= New texture added
WORD Woof3DAlert (UBYTE * text ); Description Open an Alert window with the given text message (window aspect change with OS)Special parameters NoneReturn value
WORD Woof3DCenterObjet (WORD Nobjet ,WORD Nfacette ,WORD CenterMode ); Description Center a 3D Objet to the Center (0,0,0). All the Points of Nobjet are modified.Special parameters CenterMode define how the X Y Z points are centeredReturn value 0
WORD Woof3DClear (WORD Thing ,WORD n ); Description Clear the nth Thing of the scene. Thing give the type of Thing to clearSpecial parameters n can be set to ALL to clear all given ThingsReturn value 0
WORD Woof3DClose (WORD Nthing ); Description Close definitely (and free memory of) this Scene or this WindowSpecial parameters Nthing can be an Nwindow or SCENE to close this SceneReturn value
WORD Woof3DComputeScene (WORD ComputeMode); Description The Big One function : compute and draw all the Scene (Objet,texture,facettes,etc..).Special parameters None cause the result depends only of what is defined in the Scene. ComputeMode MUST be 0Return value
WORD Woof3DCosinus (WORD angle ,WORD * cos ,WORD * sin ); Description Return the Cosinus an Sinus value of the given angle of rotation in degree * 10 Example angle=450 mean a 45° So Angle must be in 0 à 3599Special parameters NoneReturn value
WORD Woof3DDraw (WORD Nimage ,WORD x ,WORD y ,WORD large ,WORD high ,UBYTE * texte ,WORD StyleMode ,WORD state ); Description Draw a block with different Styles (TEXT, RECTANGLE,etc…) in the ImageSpecial parameters StyleModeReturn value
WORD Woof3DDrawFillRectangleRGB (WORD Nimage ,WORD x ,WORD y ,WORD large ,WORD high ,UBYTE * RGB ); Description Draw a filled rectangle in the Image. Use instead Woof3DDraw()Special parameters NoneReturn value
WORD Woof3DDrawLineRGB (WORD Nimage ,WORD x0 ,WORD y0 ,WORD x1 ,WORD y1 ,UBYTE * RGB ); Description Draw a line in the Image Use instead Woof3DDraw()Special parameters NoneReturn value
WORD Woof3DDrawPixelRGB (WORD Nimage ,WORD x ,WORD y ,UBYTE * RGB ); Description Draw a single pixel in the Image (not an efficient fonction)Special parameters NoneReturn value
WORD Woof3DDrawRectangleRGB (WORD Nimage ,WORD x ,WORD y ,WORD large ,WORD high ,UBYTE * RGB ); Description Draw a rectangle in the Image Use instead Woof3DDraw()Special parameters NoneReturn value
WORD Woof3DDrawSubImage (WORD Nimage ,WORD Nsubimage ,WORD x ,WORD y ,WORD DrawMode ); Description Draw a SubImage in the ImageSpecial parameters NoneReturn value
WORD Woof3DDrawTextRGB (WORD Nimage ,WORD x ,WORD y ,UBYTE * text ,UBYTE * RGB ); Description Draw a Text in the Image Use instead Woof3DDraw()Special parameters NoneReturn value
WORD Woof3DDrawWindow (WORD Nwindow ); Description ReDraw the Window with the 24 bits image glued to YOU SHOULD not use this function that is handled by Woof3DWindowsManager()Special parameters NoneReturn value
WORD Woof3DFileRequester (UBYTE * fileName ,UBYTE * title ); Description Open a File Requester Window (window aspect change with OS) to select a FileNameSpecial parameters NoneReturn value
WORD Woof3DGetButtonsValues (WORD Nwindow ,BOOL * click ,WORD * state ,WORD * value ); Description Fill 3 arrays with the current values of the buttons from a WindowSpecial parameters NoneReturn value
WORD Woof3DGetNumber (WORD Thing ,UBYTE * name ); Description Get the Number of a Thing from his Name. Thing give the type of Thing to obtainSpecial parameters NoneReturn value
WORD Woof3DGetPixelRGB (WORD Nimage ,WORD x ,WORD y ,UBYTE * RGB ); Description Get the RGB color of a pixel (not very usefull)Special parameters NoneReturn value
WORD Woof3DGetValuesEdition(WORD *Nobjet,WORD *Nfacette,WORD *Npoint); Description Get the selected values that can be acessed with the SELECTION parameterSpecial parameters NoneReturn value 0
WORD Woof3DGetValuesEditionMore(WORD *Nimage,WORD *Ntexture,WORD *Nelement,WORD *Nanimation,WORD *Nframe); Description Get the selected values that can be acessed with the SELECTION parameterSpecial parameters NoneReturn value 0
WORD Woof3DGetValuesPosition (WORD Nelement ,WORD * Xtheta ,WORD * Ytheta ,WORD * Ztheta ); Description Get the actual position variables from an Element (how it is turned)Special parameters NoneReturn value Nelement
WORD Woof3DGetValuesWindow (WORD Nwindow ,UBYTE * key ,WORD * state ,BOOL * mouseMove ,WORD * WinAction ,WORD * specialkey ); Description Get all the usefull variables from a windows to follow user actionsSpecial parameters key is the keyboard mouseMove is TRUE if mouse has moved state specialkeyReturn value
WORD Woof3DGetValuesXYZ(WORD Nthing,LONG *x,LONG *y,LONG *z) Description Get an actual position X Y (Z)Special parameters Nthing can be SELECTION actual edition cursor position on the 3D environnement WINDOW actual x and y mouse position (WORD converted to LONG, Z = 0) SCENE actual GlobalPosition X Y Z of the 3D Scene Nelement actual GlobalPosition X Y Z of the Element NReturn value Nthing
WORD Woof3DGetXYZpoint (WORD Nobjet ,WORD Nfacette ,WORD Npoint ,WORD * XYZpoint ); Description Give access to an array of 3 WORDs defining an XYZpoint. You can assume only an access to this unique XYZpoint.Special parameters NoneReturn value 0
WORD Woof3DImagesFX (WORD Nimage ,WORD Nimage2 ,UBYTE * RGB ,WORD ImageFXMode ); Description Apply a special effects (FX) to an 24 bits image (or 2)Special parameters ImageFXModeReturn value
WORD Woof3DLoadFile (UBYTE * filename ,UBYTE * name ); Description Load a file to the SceneSpecial parameters If filename is then this function call Woof3DFileRequester() to obtain a filename. File Formats recognized In Woof3D v1.0 those file formats are recognized and automatically stored in the Scene : Picture BMP 24 bits unpacked (to Scene/image) File Config Woof3D (to Scene) File VScape Ascii (to Scene/Objet) File Caligari 24 Ascii (to Scene/Objet) File Caligari 2 Ascii (to Scene/Objet)Return value Nthing= loaded Thing number
WORD Woof3DModify(WORD Thing,WORD parameter,WORD value); Description Modify one parameter of the SceneSpecial parameters In v1.0 only that Woof3DModify(SCENE,BACKGROUND,TRUE); Woof3DModify(SCENE,BACKGROUND,FALSE); Woof3DModify(SCENE,DRAWMODE,NEXT); Woof3DModify(SCENE,BACKGROUND,TEXTURE); or an other DrawModeReturn value
WORD Woof3DModifyScene (WORD left ,WORD right ,WORD up ,WORD down ,WORD zoom ,WORD scale ,WORD RefMode ); Description Modify some parameter of an existing SceneSpecial parameters AUTO or NONEReturn value
WORD Woof3DModifyTexture (WORD Ntexture ,WORD posX ,WORD posY ,WORD DrawMode ,WORD RefMode ); Description Modify an existing Texture posX posY define the Texture Centering. DrawMode define the drawing method for Facette/PointsSpecial parameters left,right,up,down, define in pixels a rectangle that clip the 3D image zoom activate the perspective or else should be 0 Scale enlarge the image = a 320 pixels large 3D image has a 1024 scale factor.Return value
WORD Woof3DOpenScene (WORD large ,WORD high ,WORD Nwindow ); Description First function to call for making a 3D Scene. Large and high define the size in pixels of the image (of the Scene) that will be rendered. large MUST be multiple of 32 (32,64,...,320,etc..) large and high MUST be in the range 32-1024 WindowPt is used to display this image (Window/screen).Special parameters if Nwindow is AUTO then a new Window is created with Large and high. if Large and high are AUTO then the Nwindow dimensions are used. Large and High define the maximal surface that could be rendered (in v1.0 large and high MUST be window size)Return value
WORD Woof3DOpenWindow (WORD large ,WORD high ,WORD bits ,char * name ,WORD WindowMode ,WORD nb_buttons ); Description First function to call to obtain a display (window aspect change with OS)Special parameters If all is AUTO ask user to choose resolution & modeReturn value
WORD Woof3DPrint (WORD Thing ,WORD n ); Description Print info about the nth Thing of the scene. Thing give the type of Thing to printSpecial parameters n can be set to ALL to print all given stuffsReturn value 0
WORD Woof3DSelector (UBYTE * text_list ); Description Open a Window with buttons to give a choice to userSpecial parameters texte must be of the kind Button1|Button2|Button3 that will create 3 buttons All buttons texts MUST be separate by |Return value Nbutton = the selected button from 0 to n-1
WORD Woof3DSetButton (WORD Nwindow ,WORD Nbutton ,WORD x ,WORD y ,WORD large ,WORD high ,UBYTE * text ,WORD ButtonMode ); Description Define or modify a button of the Window. This Window must have been created with buttonsSpecial parameters Return value 0
WORD Woof3DSetButtonValue(WORD Nwindow,WORD Nbutton,WORD state,WORD value) Description Change the actual button value/state. This Window must have been opened with buttons at Woof3DOpenWindow. This button must have been defined with Woof3DSetButton.Special parameters Return value 0
WORD Woof3DSetEdition (WORD Nobjet ,WORD Nfacette ,WORD Npoint ,WORD Nimage ,WORD Ntexture ,WORD Nelement ,WORD Nanimation ,WORD Nframe ,WORD EditMode ); Description Define actual selected values that can be acessed with the SELECTION parameterSpecial parameters Return value EditMode
WORD Woof3DSetElementAnimation (WORD Nelement ,WORD Nanim ); Description Assign an animation to an element. Element position will then change with the animation and time.Special parameters Return value Nelement = Element modified
WORD Woof3DSetElementPosition (WORD Nelement ,WORD RefMode ,WORD Xtheta ,WORD Ytheta ,WORD Ztheta ,LONG GlobalPosX ,LONG GlobalPosY ,LONG GlobalPosZ ); Description Define or change the position of Nelement immediatly. X Y Z theta Xtheta,Ytheta,Ztheta define the angle of rotation in degree * 10 Example Xtheta=450 mean a 45° axe X rotation Example Ztheta=3600 mean a 360° axe Z rotation Element 0 is the Scene ViewPoint see also Woof3DViewPoint() GlobalPos X Y Z GlobalPosX,GlobalPosY,GlobalPosZ define the global (universe) position If the Scene ViewPoint is also GlobalPos 0,0,0 then a element at (0,0,0) is screen centered.Special parameters Xtheta,Ytheta,Ztheta,GlobalPosX,GlobalPosY,GlobalPosZ can be NONE meaning this value is unchanged.Return value Nelement = Element modified
WORD Woof3DSetFacettesTexture (WORD Nobjet ,WORD Nfacette ,WORD Ntexture ); Description Set a Texture to an Objet or a FacetteSpecial parameters Return value
WORD Woof3DSetImageButton (WORD ButtonMode ,UBYTE * name ,WORD Nsubimage1 ,WORD Nsubimage2 ,WORD Nsubimage3 ,WORD Nsubimage4 ,WORD Nsubimage5 ); Description Define a new kind of button with the five different aspects from five SubImagesSpecial parameters Return value
WORD Woof3DSetObjetPosition (WORD Nobjet ,WORD Xtheta ,WORD Ytheta ,WORD Ztheta ,WORD Xtrans ,WORD Ytrans ,WORD Ztrans ); Description Modify a 3D Objet (Objet) to the given position. All the Points of objet n are modified (destructive function). In fact it recenter the objet to a new positionSpecial parameters Nobjet can be set to ALLReturn value Nobjet = This Objet Number
WORD Woof3DSetViewPoint (WORD Xtheta ,WORD Ytheta ,WORD Ztheta ,LONG GlobalPosX ,LONG GlobalPosY ,LONG GlobalPosZ ,WORD RefMode ); Description Define or change the position of Scene ViewPoint. Element 0 is the Scene ViewPoint see also Woof3DViewPoint() This function is equivalent to Woof3DRotMoveElement(ScenePt,0,mode,Xtheta,Ytheta,Ztheta,GlobalPosX,G GlobalPosY,GlobalPosZ);Special parameters RefMode define if the given values replace or are added to the existing values. Xtheta,Ytheta,Ztheta,GlobalPosX,GlobalPosY,GlobalPosZ can be NONE meaning this value is unchanged.Return value 0
WORD Woof3DSetWindowAction (WORD Nwindow ,WORD WinAction ); Description Force actual Window Action (Not for use)Special parameters always 0Return value
WORD Woof3DWindowsManager (WORD ManageMode); Description Manage & redraw all the opened Windows ManageMode MUST be 0Special parameters always 0Return value always 0 |
|||||||||
| PROGRAMMER'S REFERENCES - 3 Parameters | |||||||||
DrawMode define the
Texture drawing method for Facette/Points
SHADE grey shaded
TexMode is the texturing axe for Woof3DAddTexture, Woof3DModifyTexture XAXE Texture is mapped among the X axis Thing give what to use in a generic function SCENE the full Scene content
AnimMode define the type of animation ANIM_SIMPLE frames are played one time only CenterMode define how the X Y Z points are centered XYZCENTER = fully centered
RefMode define if the given values replace or are added to the existing values. ABSOLUTE all given X Y Z Theta and GlobalPos are absolute and replace the existing values File Format in Woof3D v1.0 those file formats are recognized and automatically stored in the Scene : Picture BMP 24 bits unpacked (to Scene/image) ObjetFXMode for generating a new Objet with Woof3DAddObjetFromFX () OBJET_FAN create a polygon ImageFXMode special effects (FX) to an 24 bits image (or 2) can be FX_RGB_BGR invert bytes R and B speecialkey is the keyboard non-ascii keys. Only those are defined in this version KEYPRIOR state is the actual mouse event for Windows/Buttons and can be IS_NONE mouse state undefined when program start WinAction is the action needed by the window, it got no use except for Woof3DWindowsManager() DO_NOTHING |
|||||||||
| PROGRAMMER'S REFERENCES - 4 Scenes | |||||||||
Scenes Files are simple
text files called *.w3d used as script for Woof3D they can be loaded
like this
Woof3DLoadFile("tonneau.w3d","MyScene");Without knowing C you can create *.w3d Scenes Files They alway began with the text Woof3D.V1
Usable Woof3D functions are Functions are used in a more compact way (see examples) diane.w3d an example showing almost all possibilities :
|
|||||||||
. 