Added docs/formatted existing docs for doxygen.
authorCasey Corn <cmccad@yahoo.com>
Mon, 26 May 2003 19:20:56 +0000 (19:20 +0000)
committerCasey Corn <cmccad@yahoo.com>
Mon, 26 May 2003 19:20:56 +0000 (19:20 +0000)
source/creator/buildinfo.c
source/creator/creator.c

index 6b975d1b115c5bf00ff4d212edef3210188d3984..bb6bde1757e6e15b48173268e1cd079279a60d7f 100644 (file)
@@ -1,4 +1,4 @@
-/**
+/*
  * $Id$
  *
  * ***** BEGIN GPL/BL DUAL LICENSE BLOCK *****
  *
  * ***** END GPL/BL DUAL LICENSE BLOCK *****
  */
+/**
+ * \file buildinfo.c
+ * \brief Info on the date, time, os, and type of blender build.
+ * \ingroup mainmodule
+ */
 
 #ifdef HAVE_CONFIG_H
 #include <config.h>
 #endif
 
 #ifdef BUILD_DATE
+/**
+ * Global build date.
+ */
 char * build_date=BUILD_DATE;
+/**
+ * Global build time.
+ */
 char * build_time=BUILD_TIME;
+/**
+ * Global build platform.
+ */
 char * build_platform=BUILD_PLATFORM;
+/**
+ * Global build type.
+ */
 char * build_type=BUILD_TYPE;
 #endif
index 54141ad5b3a9a3162ba4c47779a73856a863f408..dbe6e000450aa9d1799cf080ad4a6a9822a7ce80 100644 (file)
@@ -37,6 +37,8 @@
  * This file contains the int main(int,char**) function along with some helper
  * functions.
  *
+ * For some reason, doxygen wants to say that the build_* info variables are
+ * defined here.  They are really defined in buildinfo.c 
  * \todo clear out unnecessary includes
  *
  */
@@ -126,22 +128,44 @@ extern char * build_type;
 
 /*     Local Function prototypes */
 
+/**
+ * \brief Prints help message
+ * 
+ * Prints a help message to the prompt when triggered by the switches:
+ *  - "-h"
+ *  - "--help"
+ *  - "/?"
+ *
+ *  \todo document -nofrozen switch
+ */
 static void print_help();
 
 /* for the callbacks: */
 
 /**
- * For callback functions. What does this do?
+ * \brief For callback functions. What does this do?
  * \ingroup main_helpers
  * \ingroup undoc
  */
 extern int pluginapi_force_ref(void);  /* from blenpluginapi:pluginapi.c */
 
+/**
+ * \brief Holds the blender program name.
+ *
+ * Copied from argv[0].  Used for playanim and creting runtimes.
+ */
 char bprogname[FILE_MAXDIR+FILE_MAXFILE];
 
-/* Initialise callbacks for the modules that need them */
+/** \brief Initialise callbacks for the modules that need them */
 void setCallbacks(void); 
 
+/**
+ * \brief Used for trapping the SIGFPE signal.
+ *
+ * This function is passed to signal() on the following platforms:
+ *  - Alpha Linux
+ *  - SGI
+ */
 static void fpe_handler(int sig)
 {
        // printf("SIGFPE trapped\n");
@@ -193,22 +217,50 @@ static void print_help(void)
 }
 
 
+/**
+ * \todo This function is neither used nor defined in this file!
+ * It is declared in source/blender/blenlib/PIL_time.h
+ * It is defined in source/blender/blenlib/intern/time.c
+ * Should this be here?
+ *
+ */
 double PIL_check_seconds_timer(void);
+
+/* This is defined in: ??? */
 extern void winlay_get_screensize(int *width_r, int *height_r);
+
+/**
+ * \brief The main blender function.
+ *
+ * This is function is compiled into the blender executable.  It handles
+ * command line arugments and initialization.
+ */
 int main(int argc, char **argv)        
 {
        int a, i, stax, stay, sizx, sizy;
        SYS_SystemHandle syshandle;
        Scene *sce;
 
+/**
+ * First step is to initialize platform specific variables and functions, and to
+ * set the callbacks.
+ */
+/**
+ * \internal  - Turn on audio for WIN32 and linux
+ */
 #if defined(WIN32) || defined (__linux__)
        int audio = 1;
 #else
        int audio = 0;
 #endif
-
+/**
+ * \internal - Call the setCallbacks() function
+ */
        setCallbacks();
-
+/**
+ * \internal Do some apple specific initialization.
+ * \todo Does anyone know why the first #ifdef __APPLE__ is here?
+ */
 #ifdef __APPLE__
                /* patch to ignore argument finder gives us (pid?) */
        if (argc==2 && strncmp(argv[1], "-psn_", 5)==0) {
@@ -229,6 +281,9 @@ int main(int argc, char **argv)
        }
 #endif
 
+/**
+ * \internal OS specific stuff for FreeBSD, Linux alpha, and sgi.
+ */
 #ifdef __FreeBSD__
        fpsetmask(0);
 #endif
@@ -241,23 +296,40 @@ int main(int argc, char **argv)
        signal (SIGFPE, fpe_handler);
 #endif
 
-       // copy path to executable in bprogname. playanim and creting runtimes
-       // need this.
-
+       /**
+        * \internal copy path to executable in bprogname. playanim and creting runtimes need this.
+        */
        BLI_where_am_i(bprogname, argv[0]);
        
-               /* Hack - force inclusion of the plugin api functions,
-                * see blenpluginapi:pluginapi.c
+               /** \internal Hack - force inclusion of the plugin api functions,
+                *  \internal see blenpluginapi:pluginapi.c
+                *  \todo pluginapi_force_ref() is defined as a hack.  Fix this?
                 */
        pluginapi_force_ref();
        
+       /**
+        * Initialize globals, get the system handle and initialize the messaging system.
+        */
        initglobals();  /* blender.c */
 
        syshandle = SYS_GetSystem();
        GEN_init_messaging_system();
 
        /* first test for background */
+       /** \internal The G_SCENESCRIPT is always set. */
        G.f |= G_SCENESCRIPT; /* scenescript always set! */
+       /**
+        * The first for loop parses thru the following command line arguments:
+        *  - "-h", "--help", and "/?": prints a help message.
+        *  - "-a": plays animations (only when it's before the -b switch).
+        *  - "-b", "-B": sets blender to run in background mode.
+        *  - "-m": obsolete switch.
+        *  - "-y": disables python.
+        *  - "-Y": explains \e why "-y" is used to disable python.
+        * \todo Put the -h, --help, and /? flags in one if statment.
+        * \todo -a has 2 different meanings, depending on context.
+        * \todo The -m switch has been disabled.  Is there any reason to keep it here?
+        */
        for(a=1; a<argc; a++) {
 
                /* Handle unix and windows style help requests */
@@ -316,13 +388,28 @@ int main(int argc, char **argv)
                }
        }
 
+/**
+ * Set a few more options.
+ */
 #ifdef __sgi
        setuid(getuid()); /* end superuser */
 #endif
 
-       RE_init_render_data();  /* must be called here because R.winpos from default file */
+       RE_init_render_data();  /** Render initializer must be called here because R.winpos from default file */
        
+       /**
+        * If blender is not in background:
+        */
        if(G.background==0) {
+               /**
+                * Parse the following command line arguments:
+                *   - "-p": set the prefered window location and size.
+                *   - "-d": enables debugging.
+                *   - "-w": fullscreen mode.
+                *   - "-W": borderless window (MS windows only).
+                *   - "-noaudion", "-nosound": disables audio.
+                *   - "-nofrozen": disables frozen python.
+                */
                for(a=1; a<argc; a++) {
                        if(argv[a][0] == '-') {
                                switch(argv[a][1]) {
@@ -376,9 +463,9 @@ int main(int argc, char **argv)
                                case 'N':
                                        if (strcasecmp(argv[a], "-noaudio") == 0|| strcasecmp(argv[a], "-nosound") == 0) {
                                                /**
-                                                       notify the gameengine that no audio is wanted, even if the user didn't give
-                                                       the flag -g noaudio 
-                                       */
+                                                * \internal The noaudio flag notifies the gameengine that no audio is wanted,
+                                                * even if the user didn't give the flag -g noaudio.
+                                                */
 
                                                SYS_WriteCommandLineInt(syshandle,"noaudio",1);
                                                audio = 0;
@@ -394,15 +481,25 @@ int main(int argc, char **argv)
                        }
                }
 
+               /**
+                * Start the python module, and initialize audio and BIF_init().
+                */
                BPY_start_python();
                
-               /* NOTE: initialize_sound *must be* after start_python,
-                * at least on FreeBSD */
+               /**
+                * NOTE: sound_init_audio() *must be* after start_python,
+                * at least on FreeBSD.
+                */
 
                sound_init_audio();
 
                BIF_init();
        }
+       /**
+        * If blender is in background:
+        *  - Start python.
+        *  - Turn audio off.
+        */
        else {
                BPY_start_python();
                SYS_WriteCommandLineInt(syshandle,"noaudio",1);
@@ -411,6 +508,9 @@ int main(int argc, char **argv)
         if (G.f & G_DEBUG) printf("setting audio to: %d\n", audio);
        }
 
+       /**
+        * Next, initialize more stuff :)
+        */
        RE_init_filt_mask();
        
 #ifdef WITH_QUICKTIME
@@ -436,6 +536,18 @@ int main(int argc, char **argv)
 
                /* OK we are ready for it */
 
+       /**
+        * The third and final for loop processes the following arguments:
+        *  - "-p" (again): This time four args are skipped and then break;
+        *  - "-g": passes arguments to the game engine.
+        *  - "-f": renders a single frame and saves it.
+        *  - "-a": renders an animation.  "-b" must be before "-a"
+        *  - "-S": sets the starting scene name.
+        *  - "-s": sets the start frame.
+        *  - "-e": sets the end frame.
+        *  - "-R": registers the blender extensions. (MS windows only)
+        *  - <file>: sets the blender file to open.
+        */
        for(a=1; a<argc; a++) {
                if (G.afbreek==1) break;
 
@@ -448,13 +560,13 @@ int main(int argc, char **argv)
                        case 'g':
                                {
                                /**
-                               gameengine parameters are automaticly put into system
-                               -g [paramname = value]
-                               -g [boolparamname]
-                               example:
-                               -g novertexarrays
-                               -g maxvertexarraysize = 512
-                               */
+                                * gameengine parameters are automaticly put into system
+                                * -g [paramname = value]
+                                * -g [boolparamname]
+                                * example:
+                                * -g novertexarrays
+                                * -g maxvertexarraysize = 512
+                                */
 
                                        if(++a < argc) 
                                        {
@@ -537,29 +649,50 @@ int main(int argc, char **argv)
                                break;
                        }
                }
+               /**
+                * If the argument does not begin with a dash, it must be a file name.
+                */
                else {
                        BKE_read_file(argv[a], NULL);
                        sound_initialize_sounds();
                }
        }
        
+       /**
+        * If blender is in background mode, exit.
+        */
        if(G.background) 
        {
                exit_usiblender();
        }
 
+       /**
+        * Otherwise, initialize the GUI.
+        */
        setscreen(G.curscreen);
        
+       /**
+        * \internal if no scene exists, add one called "1".
+        */
        if(G.main->scene.first==0) {
                sce= add_scene("1");
                set_scene(sce);
        }
        
+       /**
+        * Start the main GUI loop.
+        */
        screenmain();
 
+       /**
+        * If everything went well, return with 0.
+        */
        return 0;
 } /* end of int main(argc,argv)        */
 
+/**
+ * Helper function for setCallbacks().
+ */
 static void error_cb(char *err)
 {
        error("%s", err);