From: bones_was_here Date: Tue, 20 Aug 2024 19:34:15 +0000 (+1000) Subject: Fix documentation in vid and PRVM headers X-Git-Url: https://git.rm.cloudns.org/?a=commitdiff_plain;h=7e784c47c1d56c6cad3399b9382a0ca0ffc66f2b;p=xonotic%2Fdarkplaces.git Fix documentation in vid and PRVM headers Also fixes a trivial warning. Signed-off-by: bones_was_here --- diff --git a/progsvm.h b/progsvm.h index fbbb7a0a..19cc82d3 100644 --- a/progsvm.h +++ b/progsvm.h @@ -80,18 +80,18 @@ typedef struct prvm_required_field_s // it belongs to prvm. typedef struct prvm_edict_private_s { - // mark for the leak detector + /// mark for the leak detector int mark; - // place in the code where it was allocated (for the leak detector) + /// place in the code where it was allocated (for the leak detector) const char *allocation_origin; } prvm_edict_private_t; typedef struct prvm_edict_s { - // true if this edict is unused + /// true if this edict is unused qbool free; - // sv.time when the object was freed (to prevent early reuse which could - // mess up client interpolation or obscure severe QuakeC bugs) + /// sv.time when the object was freed (to prevent early reuse which could + /// mess up client interpolation or obscure severe QuakeC bugs) double freetime; // engine-private fields (stored in dynamically resized array) @@ -100,8 +100,8 @@ typedef struct prvm_edict_s prvm_edict_private_t *required; prvm_vec_t *fp; prvm_int_t *ip; - // FIXME: this server pointer really means world, not server - // (it is used by both server qc and client qc, but not menu qc) + /// FIXME: this server pointer really means world, not server + /// (it is used by both server qc and client qc, but not menu qc) struct edict_engineprivate_s *server; // add other private structs as you desire // new structs have to start with the elements of prvm_edit_private_t @@ -534,9 +534,9 @@ prvm_prog_garbagecollection_state_t; // NOTE: external code has to create and free the mempools but everything else is done by prvm ! typedef struct prvm_prog_s { - double starttime; // system time when PRVM_Prog_Load was called - double inittime; // system time when QC initialization code finished (any entity created before is not a leak) - double profiletime; // system time when last PRVM_CallProfile was called (or PRVM_Prog_Load initially) + double starttime; ///< system time when PRVM_Prog_Load was called + double inittime; ///< system time when QC initialization code finished (any entity created before is not a leak) + double profiletime; ///< system time when last PRVM_CallProfile was called (or PRVM_Prog_Load initially) mfunction_t *functions; int functions_covered; char *strings; @@ -544,8 +544,8 @@ typedef struct prvm_prog_s mdef_t *fielddefs; mdef_t *globaldefs; mstatement_t *statements; - int entityfields; // number of vec_t fields in progs (some variables are 3) - int entityfieldsarea; // LadyHavoc: equal to max_edicts * entityfields (for bounds checking) + int entityfields; ///< number of vec_t fields in progs (some variables are 3) + int entityfieldsarea; ///< LadyHavoc: equal to max_edicts * entityfields (for bounds checking) // loaded values from the disk format int progs_version; @@ -566,12 +566,12 @@ typedef struct prvm_prog_s int numstrings; int numglobals; - int *statement_linenums; // NULL if not available - int *statement_columnnums; // NULL if not available + int *statement_linenums; ///< NULL if not available + int *statement_columnnums; ///< NULL if not available - double *statement_profile; // only incremented if prvm_statementprofiling is on + double *statement_profile; ///< only incremented if prvm_statementprofiling is on int statements_covered; - double *explicit_profile; // only incremented if prvm_statementprofiling is on + double *explicit_profile; ///< only incremented if prvm_statementprofiling is on int explicit_covered; int numexplicitcoveragestatements; @@ -584,8 +584,8 @@ typedef struct prvm_prog_s int maxknownstrings; int numknownstrings; - // this is updated whenever a string is removed or added - // (simple optimization of the free string search) + /// this is updated whenever a string is removed or added + /// (simple optimization of the free string search) int firstfreeknownstring; const char **knownstrings; unsigned char *knownstrings_flags; @@ -594,10 +594,10 @@ typedef struct prvm_prog_s memexpandablearray_t stringbuffersarray; - // garbage collection status + /// garbage collection status prvm_prog_garbagecollection_state_t gc; - // all memory allocations related to this vm_prog (code, edicts, strings) + /// all memory allocations related to this vm_prog (code, edicts, strings) mempool_t *progs_mempool; // [INIT] prvm_builtin_t *builtins; // [INIT] @@ -619,8 +619,8 @@ typedef struct prvm_prog_s mfunction_t *xfunction; int xstatement; - // stacktrace writes into stack[MAX_STACK_DEPTH] - // thus increase the array, so depth wont be overwritten + /// stacktrace writes into stack[MAX_STACK_DEPTH] + /// thus increase the array, so depth wont be overwritten prvm_stack_t stack[PRVM_MAX_STACK_DEPTH+1]; int depth; @@ -637,9 +637,9 @@ typedef struct prvm_prog_s struct fssearch_s *opensearches[PRVM_MAX_OPENSEARCHES]; const char * opensearches_origin[PRVM_MAX_OPENSEARCHES]; struct skeleton_s *skeletons[MAX_EDICTS]; - struct cmd_state_s *console_cmd; // points to the relevant console command interpreter for this vm (cmd_local or &cmd_server), also used to access cvars + struct cmd_state_s *console_cmd; ///< points to the relevant console command interpreter for this vm (cmd_local or &cmd_server), also used to access cvars - // buffer for storing all tempstrings created during one invocation of ExecuteProgram + /// buffer for storing all tempstrings created during one invocation of ExecuteProgram sizebuf_t tempstringsbuf; // polygonbegin, polygonvertex, polygonend state @@ -648,15 +648,15 @@ typedef struct prvm_prog_s // provided (e.g. whether the polygon is transparent), we can't really do much // with it until we have all of the data... - // this tracks the last polygonbegin's choice of - // CL_Mesh_CSQC or CL_Mesh_UI for this polygon + /// this tracks the last polygonbegin's choice of + /// CL_Mesh_CSQC or CL_Mesh_UI for this polygon struct model_s *polygonbegin_model; - // indicates if polygonbegin should be interpreted as 2d - // (clearscene sets this to false, renderscene sets this to true, drawpic - // also sets this to true) - // note that in FTEQW polygonbegin with 2 args is handled very differently, - // where the behavior is always 3D unless DRAWFLAG_2D is passed, but - // DRAWFLAG_2D conflicts with our DRAWFLAG_SCREEN. + /// indicates if polygonbegin should be interpreted as 2d + /// (clearscene sets this to false, renderscene sets this to true, drawpic + /// also sets this to true) + /// note that in FTEQW polygonbegin with 2 args is handled very differently, + /// where the behavior is always 3D unless DRAWFLAG_2D is passed, but + /// DRAWFLAG_2D conflicts with our DRAWFLAG_SCREEN. qbool polygonbegin_guess2d; // the texture name and drawflags provided to polygonbegin char polygonbegin_texname[MAX_QPATH]; @@ -666,14 +666,14 @@ typedef struct prvm_prog_s int polygonbegin_maxvertices; float *polygonbegin_vertexdata; - // copies of some vars that were former read from sv + /// copies of some vars that were former read from sv int num_edicts; - // number of edicts for which space has been (should be) allocated + /// number of edicts for which space has been (should be) allocated int max_edicts; // [INIT] - // used instead of the constant MAX_EDICTS + /// used instead of the constant MAX_EDICTS int limit_edicts; // [INIT] - // number of reserved edicts (allocated from 1) + /// number of reserved edicts (allocated from 1) int reserved_edicts; // [INIT] prvm_edict_t *edicts; @@ -684,35 +684,35 @@ typedef struct prvm_prog_s } edictsfields; void *edictprivate; - // size of the engine private struct + /// size of the engine private struct int edictprivate_size; // [INIT] prvm_prog_fieldoffsets_t fieldoffsets; prvm_prog_globaloffsets_t globaloffsets; prvm_prog_funcoffsets_t funcoffsets; - // allow writing to world entity fields, this is set by server init and - // cleared before first server frame + /// allow writing to world entity fields, this is set by server init and + /// cleared before first server frame qbool allowworldwrites; - // name of the prog, e.g. "Server", "Client" or "Menu" (used for text output) + /// name of the prog, e.g. "Server", "Client" or "Menu" (used for text output) const char *name; // [INIT] - // flag - used to store general flags like PRVM_GE_SELF, etc. + /// flag - used to store general flags like PRVM_GE_SELF, etc. unsigned flag; const char **extensionstring; // [INIT] qbool loadintoworld; // [INIT] - // used to indicate whether a prog is loaded + /// used to indicate whether a prog is loaded qbool loaded; qbool leaktest_active; - // translation buffer (only needs to be freed on unloading progs, type is private to prvm_edict.c) + /// translation buffer (only needs to be freed on unloading progs, type is private to prvm_edict.c) void *po; - // printed together with backtraces + /// printed together with backtraces const char *statestring; struct animatemodel_cache *animatemodel_cache; @@ -725,27 +725,27 @@ typedef struct prvm_prog_s //============================================================================ - mdef_t *self; // if self != 0 then there is a global self + mdef_t *self; ///< if self != 0 then there is a global self //============================================================================ // function pointers - void (*begin_increase_edicts)(struct prvm_prog_s *prog); // [INIT] used by PRVM_MEM_Increase_Edicts - void (*end_increase_edicts)(struct prvm_prog_s *prog); // [INIT] + void (*begin_increase_edicts)(struct prvm_prog_s *prog); ///< [INIT] used by PRVM_MEM_Increase_Edicts + void (*end_increase_edicts)(struct prvm_prog_s *prog); ///< [INIT] - void (*init_edict)(struct prvm_prog_s *prog, prvm_edict_t *edict); // [INIT] used by PRVM_ED_ClearEdict - void (*free_edict)(struct prvm_prog_s *prog, prvm_edict_t *ed); // [INIT] used by PRVM_ED_Free + void (*init_edict)(struct prvm_prog_s *prog, prvm_edict_t *edict); ///< [INIT] used by PRVM_ED_ClearEdict + void (*free_edict)(struct prvm_prog_s *prog, prvm_edict_t *ed); ///< [INIT] used by PRVM_ED_Free - void (*count_edicts)(struct prvm_prog_s *prog); // [INIT] used by PRVM_ED_Count_f + void (*count_edicts)(struct prvm_prog_s *prog); ///< [INIT] used by PRVM_ED_Count_f - qbool (*load_edict)(struct prvm_prog_s *prog, prvm_edict_t *ent); // [INIT] used by PRVM_ED_LoadFromFile + qbool (*load_edict)(struct prvm_prog_s *prog, prvm_edict_t *ent); ///< [INIT] used by PRVM_ED_LoadFromFile - void (*init_cmd)(struct prvm_prog_s *prog); // [INIT] used by PRVM_InitProg - void (*reset_cmd)(struct prvm_prog_s *prog); // [INIT] used by PRVM_ResetProg + void (*init_cmd)(struct prvm_prog_s *prog); ///< [INIT] used by PRVM_InitProg + void (*reset_cmd)(struct prvm_prog_s *prog); ///< [INIT] used by PRVM_ResetProg - void (*error_cmd)(const char *format, ...) DP_FUNC_PRINTF(1); // [INIT] + void (*error_cmd)(const char *format, ...) DP_FUNC_PRINTF(1); ///< [INIT] - void (*ExecuteProgram)(struct prvm_prog_s *prog, func_t fnum, const char *errormessage); // pointer to one of the *VM_ExecuteProgram functions + void (*ExecuteProgram)(struct prvm_prog_s *prog, func_t fnum, const char *errormessage); ///< pointer to one of the *VM_ExecuteProgram functions } prvm_prog_t; typedef enum prvm_progindex_e @@ -759,7 +759,7 @@ prvm_progindex_t; extern prvm_prog_t prvm_prog_list[PRVM_PROG_MAX]; prvm_prog_t *PRVM_ProgFromString(const char *str); -prvm_prog_t *PRVM_FriendlyProgFromString(const char *str); // for console commands (prints error if name unknown and returns NULL, prints error if prog not loaded and returns NULL) +prvm_prog_t *PRVM_FriendlyProgFromString(const char *str); ///< for console commands (prints error if name unknown and returns NULL, prints error if prog not loaded and returns NULL) #define PRVM_GetProg(n) (&prvm_prog_list[(n)]) #define PRVM_ProgLoaded(n) (PRVM_GetProg(n)->loaded) #define SVVM_prog (&prvm_prog_list[PRVM_PROG_SERVER]) @@ -779,7 +779,7 @@ extern const int vm_sv_numbuiltins; extern const int vm_cl_numbuiltins; extern const int vm_m_numbuiltins; -extern const char *vm_sv_extensions[]; // client also uses this +extern const char *vm_sv_extensions[]; ///< client also uses this extern const char *vm_m_extensions[]; void SVVM_init_cmd(prvm_prog_t *prog); @@ -892,8 +892,9 @@ unsigned int PRVM_EDICT_NUM_ERROR(prvm_prog_t *prog, unsigned int n, const char //#define PRVM_E_VECTOR(e,o) (&(e->fields.fp[o])) #define PRVM_E_STRING(e,o) (PRVM_GetString(prog, e->fields.ip[o])) -extern int prvm_type_size[8]; // for consistency : I think a goal of this sub-project is to -// make the new vm mostly independent from the old one, thus if it's necessary, I copy everything +/// for consistency : I think a goal of this sub-project is to +/// make the new vm mostly independent from the old one, thus if it's necessary, I copy everything +extern int prvm_type_size[8]; void PRVM_Init_Exec(prvm_prog_t *prog); @@ -916,13 +917,13 @@ char *PRVM_GlobalStringNoContents(prvm_prog_t *prog, int ofs, char *line, size_t //============================================================================ -/* +/** Initializing a vm: Call InitProg with the num Set up the fields marked with [INIT] in the prog struct Load a program with LoadProgs +NB: Load expects to be called right after Reset (which is called by Init) */ -// Load expects to be called right after Reset void PRVM_Prog_Init(prvm_prog_t *prog, struct cmd_state_s *cmd); void PRVM_Prog_Load(prvm_prog_t *prog, const char *filename, unsigned char *data, fs_offset_t size, void CheckRequiredFuncs(prvm_prog_t *prog, const char *filename), int numrequiredfields, prvm_required_field_t *required_field, int numrequiredglobals, prvm_required_field_t *required_global); void PRVM_Prog_Reset(prvm_prog_t *prog); diff --git a/prvm_execprogram.h b/prvm_execprogram.h index 194c5a0f..2a70bfc8 100644 --- a/prvm_execprogram.h +++ b/prvm_execprogram.h @@ -37,7 +37,7 @@ int i; #if USE_COMPUTED_GOTOS // Must exactly match opcode_e enum in pr_comp.h - const static void *dispatchtable[] = { + static const void *dispatchtable[] = { &&handle_OP_DONE, &&handle_OP_MUL_F, &&handle_OP_MUL_V, diff --git a/vid.h b/vid.h index 1fc93ef7..f1d57ab6 100644 --- a/vid.h +++ b/vid.h @@ -41,8 +41,8 @@ renderpath_t; typedef struct viddef_support_s { - int glversion; // this is at least 32 - int glshaderversion; // this is at least 150 (GL 3.2) + int glversion; ///< this is at least 32 + int glshaderversion; ///< this is at least 150 (GL 3.2) qbool amd_texture_texture4; qbool arb_texture_gather; qbool ext_texture_compression_s3tc; @@ -72,13 +72,13 @@ typedef struct viddef_s // used in many locations in the renderer viddef_mode_t mode; ///< currently active video mode qbool stencil; - qbool sRGB2D; // whether 2D rendering is sRGB corrected (based on sRGBcapable2D) - qbool sRGB3D; // whether 3D rendering is sRGB corrected (based on sRGBcapable3D) - qbool sRGBcapable2D; // whether 2D rendering can be sRGB corrected (renderpath) - qbool sRGBcapable3D; // whether 3D rendering can be sRGB corrected (renderpath) + qbool sRGB2D; ///< whether 2D rendering is sRGB corrected (based on sRGBcapable2D) + qbool sRGB3D; ///< whether 3D rendering is sRGB corrected (based on sRGBcapable3D) + qbool sRGBcapable2D; ///< whether 2D rendering can be sRGB corrected (renderpath) + qbool sRGBcapable3D; ///< whether 3D rendering can be sRGB corrected (renderpath) renderpath_t renderpath; - qbool allowalphatocoverage; // indicates the GL_AlphaToCoverage function works on this renderpath and framebuffer + qbool allowalphatocoverage; ///< indicates the GL_AlphaToCoverage function works on this renderpath and framebuffer unsigned int maxtexturesize_2d; unsigned int maxtexturesize_3d; @@ -88,12 +88,12 @@ typedef struct viddef_s viddef_support_t support; - int forcetextype; // always use GL_BGRA for D3D, always use GL_RGBA for GLES, etc + int forcetextype; ///< always use GL_BGRA for D3D, always use GL_RGBA for GLES, etc - int xPos, yPos; // current virtual position of the top left corner of the SDL window + int xPos, yPos; ///< current virtual position of the top left corner of the SDL window } viddef_t; -// global video state +/// global video state extern viddef_t vid; #define MAXJOYAXIS 16 @@ -101,9 +101,9 @@ extern viddef_t vid; #define MAXJOYBUTTON 36 typedef struct vid_joystate_s { - float axis[MAXJOYAXIS]; // -1 to +1 - unsigned char button[MAXJOYBUTTON]; // 0 or 1 - qbool is360; // indicates this joystick is a Microsoft Xbox 360 Controller For Windows + float axis[MAXJOYAXIS]; ///< -1 to +1 + unsigned char button[MAXJOYBUTTON]; ///< 0 or 1 + qbool is360; ///< indicates this joystick is a Microsoft Xbox 360 Controller For Windows } vid_joystate_t; @@ -183,11 +183,11 @@ extern cvar_t gl_info_version; extern cvar_t gl_info_extensions; extern cvar_t gl_info_driver; -// brand of graphics chip +/// brand of graphics chip extern const char *gl_vendor; -// graphics chip model and other information +/// graphics chip model and other information extern const char *gl_renderer; -// begins with 1.0.0, 1.1.0, 1.2.0, 1.2.1, 1.3.0, 1.3.1, or 1.4.0 +/// begins with 1.0.0, 1.1.0, 1.2.0, 1.2.1, 1.3.0, 1.3.1, or 1.4.0 extern const char *gl_version; @@ -202,22 +202,22 @@ void GL_Setup(void); void VID_ClearExtensions(void); +/// Called at startup void VID_Init (void); -// Called at startup +/// Called at shutdown void VID_Shutdown (void); -// Called at shutdown +/// sets the mode; only used by the Quake engine for resetting to mode 0 (the +/// base mode) on memory allocation failures int VID_SetMode (int modenum); -// sets the mode; only used by the Quake engine for resetting to mode 0 (the -// base mode) on memory allocation failures +/// allocates and opens an appropriate OpenGL context (and its window) qbool VID_InitMode(const viddef_mode_t *mode); -// allocates and opens an appropriate OpenGL context (and its window) -// updates cachegamma variables and bumps vid_gammatables_serial if anything changed -// (ONLY to be called from VID_Finish!) +/// updates cachegamma variables and bumps vid_gammatables_serial if anything changed +/// (ONLY to be called from VID_Finish!) void VID_UpdateGamma(void); qbool VID_HasScreenKeyboardSupport(void); @@ -231,10 +231,12 @@ void VID_Restart_f(struct cmd_state_s *cmd); void VID_Start(void); void VID_Stop(void); -extern unsigned int vid_gammatables_serial; // so other subsystems can poll if gamma parameters have changed; this starts with 0 and gets increased by 1 each time the gamma parameters get changed and VID_BuildGammaTables should be called again -extern qbool vid_gammatables_trivial; // this is set to true if all color control values are at default setting, and it therefore would make no sense to use the gamma table -void VID_BuildGammaTables(unsigned short *ramps, int rampsize); // builds the current gamma tables into an array (needs 3*rampsize items) -void VID_ApplyGammaToColor(const float *rgb, float *out); // applies current gamma settings to a color (0-1 range) +extern unsigned int vid_gammatables_serial; ///< so other subsystems can poll if gamma parameters have changed; this starts with 0 and gets increased by 1 each time the gamma parameters get changed and VID_BuildGammaTables should be called again +extern qbool vid_gammatables_trivial; ///< this is set to true if all color control values are at default setting, and it therefore would make no sense to use the gamma table +/// builds the current gamma tables into an array (needs 3*rampsize items) +void VID_BuildGammaTables(unsigned short *ramps, int rampsize); +/// applies current gamma settings to a color (0-1 range) +void VID_ApplyGammaToColor(const float *rgb, float *out); typedef struct {