getting started

edited March 2009 in Help request
hi,

i'm going through some examples/tutorials, trying to figure out the syntax and structure, so i tracing through the documentation. i was wondering, for similar code below;
orxViewport_SetBackgroundColor(orxVIEWPORT *_pstViewport, orxRGBA _stColor);

where is "orxRGBA _stColor" defined here? and how would i know what input is expected (ie. arrays, int, float, etc).

i also see a lot of prefixes to these variables (orx, st, pst, str, b, pf, etc), are these variable types, what is the naming convention?

Comments

  • edited March 2009
    Hi rotor!

    The orxRGBA is defined in orxType.h, but I'll soon replace all occurences with orxCOLOR structure I think.

    As for changing the viewport background, you can do it through config files (have a look to CreationTemplate.ini and SettingsTemplate.ini which contains all the aspects you can control through config).

    So for a viewport, you'll have in your config file:

    [MyViewport]
    BackgroundColor=(255, 255, 255); <= That's white ( R, G, B )

    orxRGBA can be created with help of macros (orx2RGBA, for example, everything's in orxType.h).

    Basically, a orxRGBA is an unsigned int (32bits) that contains Red, Blue, Green and Alpha (in this order). But you can use the macros to get the color you want.
    Anyway, as stated before, orxCOLOR will replace it (it's a structure with separate alpha and a vector for color).

    As for the prefix, here they are:
    - orx, prefixes all types, functions coming from orx
    - st: variable is a structure
    - p: pointer so pst is a pointer on structure, pf a pointer on float, ...
    - b: boolean
    - f: float
    - c: char
    - a: array => ac is an array of char
    - u32: unsigned 32 bits
    - s8: signed 8 bits
    - e: enum
    - z: zero-terminated string
    - s: static
    - h: handle
    - v: vector (maths)

    I may ha ve forgotten some, but that should give you an idea.

    In addition to that, a function always begins by the name of its module (orxConfig_GetBool(), orxGraphic_SetData(), ...), and the first argument is the object on which we want to do the action.
    When functions give outputs as parameters, those are usually the last parameters.

    Parameters are always prefixed with _, this makes it easy to know if you're using a local variable or a parameter.

    Macros are always in upper case whereas functions are CamelCase.

    Hope this helps! If you have any other questions, please ask them! =) Comments and ideas are also welcome! :)
  • edited March 2009
    iarwain, thanks: you're a prince! you covered a lot of matter i am trying to comprehend at the moment! i will continue digging to see if i can start making sense of it all :)

    the background colour i something i am toying with because i am trying to program something fairly basic like a keystroke that changes the background colour, ie. something to give me direct feedback to an input as a sort of debugging thing for the lack of a better term :)
  • edited March 2009
    My pleasure if it helped you! :)

    As for the basic start, I think it's the best way to begin. By the way, are you using the released 0.9.1 version or the one on the subversion repository?
    As there are a lot of simplified things and a brand new input system on the repository version, which is pretty handy to use, but I'm sure there's room to improve given external feedbacks! ;)

    Also, I'm trying to start an irc channel, for now I'm on irx.freenode.org, channel #orx-projectm if you want to join so I can help you more efficiently (if you need it, of course! ;)).
  • edited March 2009
    hi,

    thanks for speaking to me on IRC yesterday. i thought before venturing in painful and demotivating trial-and-error approach of programming from scratch, i'd thought to attempt to gain an understand of the provided example code.

    i have been grinding through cplusplus.com documentation on basic object oriented programming and other syntax related stuff, which has helped tremendously on being able to read the code (the naming convention is really great, by the way!). now i am tracing through some code to see how these principles are applied in actual implementation, and i have a few questions so far:
    typedef struct __orxCLOCK_t                           orxCLOCK;
    

    this is a rather basic question, i understand you are creating the object __orxCLOCK_t here, but i don't understand the orxCLOCK in this syntax, can you explain this further?


    i also notice a lot of code interfacing with orxSTATUS, can you perhaps explain the basic use of this? there are also a lot of occurences of orxFASTCALL, can you shed some light on this as well?
  • edited March 2009
    Hi rotor!
    thanks for speaking to me on IRC yesterday. i thought before venturing in painful and demotivating trial-and-error approach of programming from scratch, i'd thought to attempt to gain an understand of the provided example code.

    You're welcome! I'll try to maintain this IRC channel in the future, when there'll be more users! :)
    i have been grinding through cplusplus.com documentation on basic object oriented programming and other syntax related stuff, which has helped tremendously on being able to read the code (the naming convention is really great, by the way!). now i am tracing through some code to see how these principles are applied in actual implementation, and i have a few questions so far:
    typedef struct __orxCLOCK_t                           orxCLOCK;
    

    this is a rather basic question, i understand you are creating the object __orxCLOCK_t here, but i don't understand the orxCLOCK in this syntax, can you explain this further?

    Actually a typedef works like an alias. Here it gives the name orxCLOCK to the structure struct __orxCLOCK_t which is an internal type in orx. You don't know what this structure contains and you can only interact with it through orxClock_* functions.
    i also notice a lot of code interfacing with orxSTATUS, can you perhaps explain the basic use of this?

    orxSTATUS is an enum used as return type of a lot of orx functions: it tells the caller if the function succeed or failed. Usually boolean (or int) are used for this, but you then have to remember if 0 is success or not...
    Here, the values are self explanatory: orxSTATUS_FAILURE / orxSTATUS_SUCCESS. =)
    there are also a lot of occurences of orxFASTCALL, can you shed some light on this as well?

    orxFASTCALL is a macro that specify the fastcall convention for the function it is applied to. It's a macro because all the compilers don't use the same syntax for this.


    Basically, in C, you have 3 main calling conventions: cdecl, stdcall and fastcall.

    When you call a function that use the cdecl or stdcall convention, all the paremeters are pushed on the stack. When you use the fastcall, generally the first 2 parameters are passed using CPU registers (which are faster to access than the stack). So you'll see that most of the functions in orx that have parameters use the fastcall calling convention. There are some exceptions with some plugins functions, for example.
    Variadic functions (using ... as last parameters) are also an exception: they need to use the cdecl calling convention (it's a matter of whose cleaning the stack, and with ... functions, only the caller knows how many parameters were really passed, so the caller needs to clean after the call. On the contrary, stdcall makes the callee clean the parameters from the stack: it's usually a bit faster and results in a smaller code (cleaning is only done by the callee at one place, instead of being done X times by the X callers to this function).


    Hope this helps! =)
Sign In or Register to comment.