alice.mosphere.at / sdl-gpu
this repo has no description
0
fork

Configure Feed

Select the types of activity you want to include in your feed.

Added doxygen module grouping to SDL_gpu.h

grimfang4@gmail.com 09d7c402 7156f0b8

+124 -37
+124 -37
SDL_gpu/SDL_gpu.h
··· 17 17 18 18 /* Auto-detect if we're using the SDL2 API by the headers available. */ 19 19 #if SDL_VERSION_ATLEAST(2,0,0) 20 - #define SDL_GPU_USE_SDL2 20 + #define SDL_GPU_USE_SDL2 21 21 #endif 22 22 23 23 typedef struct GPU_Renderer GPU_Renderer; 24 24 typedef struct GPU_Target GPU_Target; 25 25 26 - /*! A struct representing a rectangular area with floating point precision. 26 + /*! 27 + * \defgroup Initialization Initialization 28 + * \defgroup Logging Debugging, Logging, and Error Handling 29 + * \defgroup RendererSetup Renderer Setup 30 + * \defgroup RendererControls Renderer Controls 31 + * \defgroup ContextControls Context Controls 32 + * \defgroup TargetControls Target Controls 33 + * \defgroup SurfaceControls Surface Controls 34 + * \defgroup ImageControls Image Controls 35 + * \defgroup Conversions Surface, Image, and Target Conversions 36 + * \defgroup Rendering Rendering 37 + * \defgroup Shapes Shapes 38 + * \defgroup ShaderInterface Shader Interface 39 + */ 40 + 41 + /*! \ingroup Rendering 42 + * A struct representing a rectangular area with floating point precision. 27 43 * \see GPU_MakeRect() 28 44 */ 29 45 typedef struct GPU_Rect ··· 48 64 static const GPU_RendererEnum GPU_RENDERER_D3D10 = 0x20000; 49 65 static const GPU_RendererEnum GPU_RENDERER_D3D11 = 0x40000; 50 66 51 - /*! Renderer ID object for identifying a specific renderer. 67 + /*! \ingroup Initialization 68 + * \ingroup RendererSetup 69 + * \ingroup RendererControls 70 + * Renderer ID object for identifying a specific renderer. 52 71 * \see GPU_MakeRendererID() 53 72 * \see GPU_InitRendererByID() 54 73 */ ··· 62 81 } GPU_RendererID; 63 82 64 83 65 - /*! Blend component functions 84 + /*! \ingroup ImageControls 85 + * Blend component functions 66 86 * \see GPU_SetBlendFunction() 67 87 * Values chosen for direct OpenGL compatibility. 68 88 */ ··· 79 99 GPU_FUNC_ONE_MINUS_DST_ALPHA = 0x0305 80 100 } GPU_BlendFuncEnum; 81 101 82 - /*! Blend component equations 102 + /*! \ingroup ImageControls 103 + * Blend component equations 83 104 * \see GPU_SetBlendEquation() 84 105 * Values chosen for direct OpenGL compatibility. 85 106 */ ··· 89 110 GPU_EQ_REVERSE_SUBTRACT = 0x800B 90 111 } GPU_BlendEqEnum; 91 112 92 - /*! Blend mode storage struct */ 113 + /*! \ingroup ImageControls 114 + * Blend mode storage struct */ 93 115 typedef struct GPU_BlendMode 94 116 { 95 117 GPU_BlendFuncEnum source_color; ··· 101 123 GPU_BlendEqEnum alpha_equation; 102 124 } GPU_BlendMode; 103 125 104 - /*! Blend mode presets 126 + /*! \ingroup ImageControls 127 + * Blend mode presets 105 128 * \see GPU_SetBlendMode() 106 129 * \see GPU_GetBlendModeFromPreset() 107 130 */ ··· 118 141 GPU_BLEND_NORMAL_ADD_ALPHA = 9 119 142 } GPU_BlendPresetEnum; 120 143 121 - /*! Image filtering options. These affect the quality/interpolation of colors when images are scaled. 144 + /*! \ingroup ImageControls 145 + * Image filtering options. These affect the quality/interpolation of colors when images are scaled. 122 146 * \see GPU_SetImageFilter() 123 147 */ 124 148 typedef enum { ··· 127 151 GPU_FILTER_LINEAR_MIPMAP = 2 128 152 } GPU_FilterEnum; 129 153 130 - /*! Snap modes. Blitting with these modes will align the sprite with the target's pixel grid. 154 + /*! \ingroup ImageControls 155 + * Snap modes. Blitting with these modes will align the sprite with the target's pixel grid. 131 156 * \see GPU_SetSnapMode() 132 157 * \see GPU_GetSnapMode() 133 158 */ ··· 139 164 } GPU_SnapEnum; 140 165 141 166 142 - /*! Image wrapping options. These affect how images handle src_rect coordinates beyond their dimensions when blitted. 167 + /*! \ingroup ImageControls 168 + * Image wrapping options. These affect how images handle src_rect coordinates beyond their dimensions when blitted. 143 169 * \see GPU_SetWrapMode() 144 170 */ 145 171 typedef enum { ··· 148 174 GPU_WRAP_MIRRORED = 2 149 175 } GPU_WrapEnum; 150 176 151 - /*! Image format enum 177 + /*! \ingroup ImageControls 178 + * Image format enum 152 179 * \see GPU_CreateImage() 153 180 */ 154 181 typedef enum { ··· 164 191 165 192 166 193 167 - /*! Image object for containing pixel/texture data. 194 + /*! \ingroup ImageControls 195 + * Image object for containing pixel/texture data. 168 196 * A GPU_Image can be created with GPU_CreateImage(), GPU_LoadImage(), GPU_CopyImage(), or GPU_CopyImageFromSurface(). 169 197 * Free the memory with GPU_FreeImage() when you're done. 170 198 * \see GPU_CreateImage() ··· 198 226 } GPU_Image; 199 227 200 228 201 - /*! Camera object that determines viewing transform. 229 + /*! \ingroup TargetControls 230 + * Camera object that determines viewing transform. 202 231 * \see GPU_SetCamera() 203 232 * \see GPU_GetDefaultCamera() 204 233 * \see GPU_GetCamera() ··· 211 240 } GPU_Camera; 212 241 213 242 214 - /*! Container for the built-in shader attribute and uniform locations (indices). 243 + /*! \ingroup ShaderInterface 244 + * Container for the built-in shader attribute and uniform locations (indices). 215 245 * \see GPU_LoadShaderBlock() 216 246 * \see GPU_SetShaderBlock() 217 247 */ ··· 232 262 #define GPU_MATRIX_STACK_MAX 5 233 263 #endif 234 264 235 - /*! Matrix stack data structure for replacing the old OpenGL matrix stack. */ 265 + /*! \ingroup Rendering 266 + * Matrix stack data structure for replacing the old OpenGL matrix stack. */ 236 267 typedef struct GPU_MatrixStack 237 268 { 238 269 unsigned int size; ··· 240 271 } GPU_MatrixStack; 241 272 242 273 243 - /*! Rendering context data. Only GPU_Targets which represent windows will store this. */ 274 + /*! \ingroup ContextControls 275 + * Rendering context data. Only GPU_Targets which represent windows will store this. */ 244 276 typedef struct GPU_Context 245 277 { 246 278 /*! SDL_GLContext */ 247 - void* context; 279 + void* context; 248 280 Uint8 failed; 249 281 250 282 /*! SDL window ID */ ··· 276 308 } GPU_Context; 277 309 278 310 279 - /*! Render target object for use as a blitting destination. 311 + /*! \ingroup TargetControls 312 + * Render target object for use as a blitting destination. 280 313 * A GPU_Target can be created from a GPU_Image with GPU_LoadTarget(). 281 314 * A GPU_Target can also represent a separate window with GPU_CreateTargetFromWindow(). In that case, 'context' is allocated and filled in. 282 315 * Note: You must have passed the SDL_WINDOW_OPENGL flag to SDL_CreateWindow() for OpenGL renderers to work with new windows. ··· 308 341 Uint8 is_alias; 309 342 }; 310 343 311 - /*! Important GPU features which may not be supported depending on a device's extension support. Can be OR'd together. 344 + /*! \ingroup Initialization 345 + * Important GPU features which may not be supported depending on a device's extension support. Can be OR'd together. 312 346 * \see GPU_IsFeatureEnabled() 313 347 * \see GPU_SetPreInitFlags() 314 348 * \see GPU_GetPreInitFlags() ··· 341 375 342 376 typedef Uint32 GPU_WindowFlagEnum; 343 377 344 - /*! Initialization flags for changing default init parameters. Can be bitwise OR'ed together with GPU_FeatureEnums. 378 + /*! \ingroup Initialization 379 + * Initialization flags for changing default init parameters. Can be bitwise OR'ed together with GPU_FeatureEnums. 345 380 * Default (0) is to use late swap vsync and double buffering. 346 381 * \see GPU_SetPreInitFlags() 347 382 * \see GPU_GetPreInitFlags() ··· 356 391 357 392 static const Uint32 GPU_NONE = 0x0; 358 393 359 - /*! Bit flags for the blit batch functions. 394 + /*! \ingroup Rendering 395 + * Bit flags for the blit batch functions. 360 396 * \see GPU_BlitBatch() 361 397 * \see GPU_BlitBatchSeparate() 362 398 */ ··· 370 406 371 407 #define GPU_PASSTHROUGH_ALL (GPU_PASSTHROUGH_VERTICES | GPU_PASSTHROUGH_TEXCOORDS | GPU_PASSTHROUGH_COLORS) 372 408 373 - /*! Type enumeration for GPU_AttributeFormat specifications. */ 409 + /*! \ingroup ShaderInterface 410 + * Type enumeration for GPU_AttributeFormat specifications. 411 + */ 374 412 typedef Uint32 GPU_TypeEnum; 375 413 // Use OpenGL's values for simpler translation 376 414 static const GPU_TypeEnum GPU_TYPE_BYTE = 0x1400; ··· 387 425 388 426 389 427 390 - /*! Shader type enum. 428 + /*! \ingroup ShaderInterface 429 + * Shader type enum. 391 430 * \see GPU_LoadShader() 392 431 * \see GPU_CompileShader() 393 432 * \see GPU_CompileShader_RW() ··· 401 440 402 441 403 442 404 - /*! Type enumeration for the shader language used by the renderer. */ 443 + /*! \ingroup ShaderInterface 444 + * Type enumeration for the shader language used by the renderer. 445 + */ 405 446 typedef enum { 406 447 GPU_LANGUAGE_NONE = 0, 407 448 GPU_LANGUAGE_ARB_ASSEMBLY = 1, ··· 411 452 GPU_LANGUAGE_CG = 5 412 453 } GPU_ShaderLanguageEnum; 413 454 455 + /*! \ingroup ShaderInterface */ 414 456 typedef struct GPU_AttributeFormat 415 457 { 416 458 Uint8 is_per_sprite; // Per-sprite values are expanded to 4 vertices ··· 421 463 int offset_bytes; // Number of bytes to skip at the beginning of 'values' 422 464 } GPU_AttributeFormat; 423 465 466 + /*! \ingroup ShaderInterface */ 424 467 typedef struct GPU_Attribute 425 468 { 426 469 int location; ··· 428 471 GPU_AttributeFormat format; 429 472 } GPU_Attribute; 430 473 474 + /*! \ingroup ShaderInterface */ 431 475 typedef struct GPU_AttributeSource 432 476 { 433 477 Uint8 enabled; ··· 442 486 } GPU_AttributeSource; 443 487 444 488 445 - /*! Type enumeration for error codes. 489 + /*! \ingroup Logging 490 + * Type enumeration for error codes. 446 491 * \see GPU_PushErrorCode() 447 492 * \see GPU_PopErrorCode() 448 493 */ ··· 456 501 GPU_ERROR_FILE_NOT_FOUND = 6 457 502 } GPU_ErrorEnum; 458 503 459 - 504 + /*! \ingroup Logging */ 460 505 typedef struct GPU_ErrorObject 461 506 { 462 507 char* function; ··· 465 510 } GPU_ErrorObject; 466 511 467 512 468 - /*! Type enumeration for debug levels. 513 + /*! \ingroup Logging 514 + * Type enumeration for debug levels. 469 515 * \see GPU_SetDebugLevel() 470 516 * \see GPU_GetDebugLevel() 471 517 */ ··· 505 551 506 552 507 553 508 - // Setup calls 554 + /*! \ingroup Initialization 555 + * @{ */ 509 556 510 557 // Visual C does not support static inline 511 558 #ifdef _MSC_VER ··· 568 615 /*! Clean up the renderer state and shut down SDL_gpu. */ 569 616 void GPU_Quit(void); 570 617 618 + // End of Initialization 619 + /*! @} */ 571 620 572 621 573 622 574 623 // Debugging, logging, and error handling 624 + 625 + /*! \ingroup Logging 626 + * @{ */ 575 627 576 628 /*! Sets the global debug level. 577 629 * GPU_DEBUG_LEVEL_0: Normal ··· 608 660 /*! Gets the string representation of an error code. */ 609 661 const char* GPU_GetErrorString(GPU_ErrorEnum error); 610 662 663 + // End of Logging 664 + /*! @} */ 611 665 612 666 613 667 ··· 615 669 616 670 617 671 618 - // Renderer setup controls 672 + /*! \ingroup RendererSetup 673 + * @{ */ 619 674 620 675 /*! Translates a GPU_RendererEnum into a string. */ 621 676 const char* GPU_GetRendererEnumString(GPU_RendererEnum id); ··· 638 693 /*! Deletes the renderer matching the given identifier. */ 639 694 void GPU_RemoveRenderer(GPU_RendererID id); 640 695 696 + // End of RendererSetup 697 + /*! @} */ 641 698 642 699 643 - // Renderer controls 700 + 701 + /*! \ingroup RendererControls 702 + * @{ */ 644 703 645 704 /*! Gets the number of active (created) renderers. */ 646 705 int GPU_GetNumActiveRenderers(void); ··· 663 722 /*! Reapplies the renderer state to the backend API (e.g. OpenGL, Direct3D). Use this if you want SDL_gpu to be able to render after you've used direct backend calls. */ 664 723 void GPU_ResetRendererState(void); 665 724 725 + // End of RendererControls 726 + /*! @} */ 666 727 667 728 668 729 669 730 670 731 // Context / window controls 671 732 733 + /*! \ingroup ContextControls 734 + * @{ */ 735 + 672 736 /*! \return The renderer's current context target. */ 673 737 GPU_Target* GPU_GetContextTarget(void); 674 738 ··· 722 786 /*! Returns the current line thickness value. */ 723 787 float GPU_GetLineThickness(void); 724 788 789 + // End of ContextControls 790 + /*! @} */ 725 791 726 792 727 793 728 794 729 - // Target controls 795 + /*! \ingroup TargetControls 796 + * @{ */ 730 797 731 798 /*! Creates a target that aliases the given target. Aliases can be used to store target settings (e.g. viewports) for easy switching. 732 799 * GPU_FreeTarget() frees the alias's memory, but does not affect the original. */ ··· 801 868 */ 802 869 void GPU_SetTargetRGBA(GPU_Target* target, Uint8 r, Uint8 g, Uint8 b, Uint8 a); 803 870 871 + // End of TargetControls 872 + /*! @} */ 804 873 805 874 806 875 807 - // Surface controls 876 + /*! \ingroup SurfaceControls 877 + * @{ */ 808 878 809 879 /*! Load surface from an image file that is supported by this renderer. Don't forget to SDL_FreeSurface() it. */ 810 880 SDL_Surface* GPU_LoadSurface(const char* filename); ··· 812 882 /*! Save surface to a file. The file type is deduced from the extension. Supported formats are: png, bmp, tga. Returns 0 on failure. */ 813 883 Uint8 GPU_SaveSurface(SDL_Surface* surface, const char* filename); 814 884 885 + // End of SurfaceControls 886 + /*! @} */ 815 887 816 888 817 889 818 890 819 - // Image controls 891 + /*! \ingroup ImageControls 892 + * @{ */ 820 893 821 894 /*! Create a new, blank image with the given format. Don't forget to GPU_FreeImage() it. 822 895 * \param w Image width in pixels ··· 889 962 /*! Sets the image wrapping mode, if supported by the renderer. */ 890 963 void GPU_SetWrapMode(GPU_Image* image, GPU_WrapEnum wrap_mode_x, GPU_WrapEnum wrap_mode_y); 891 964 965 + // End of ImageControls 966 + /*! @} */ 892 967 893 968 894 969 // Surface / Image / Target conversions 970 + /*! \ingroup Conversions 971 + * @{ */ 895 972 896 973 /*! Copy SDL_Surface data into a new GPU_Image. Don't forget to SDL_FreeSurface() the surface and GPU_FreeImage() the image.*/ 897 974 GPU_Image* GPU_CopyImageFromSurface(SDL_Surface* surface); ··· 905 982 /*! Copy GPU_Image data into a new SDL_Surface. Don't forget to SDL_FreeSurface() the surface and GPU_FreeImage() the image.*/ 906 983 SDL_Surface* GPU_CopySurfaceFromImage(GPU_Image* image); 907 984 985 + // End of Conversions 986 + /*! @} */ 908 987 909 988 910 - // Rendering 989 + /*! \ingroup Rendering 990 + * @{ */ 911 991 912 992 /*! Clears the contents of the given render target. Fills the target with color {0, 0, 0, 0}. */ 913 993 void GPU_Clear(GPU_Target* target); ··· 994 1074 /*! Updates the given target's associated window. */ 995 1075 void GPU_Flip(GPU_Target* target); 996 1076 1077 + // End of Rendering 1078 + /*! @} */ 997 1079 998 1080 999 1081 1000 1082 1001 1083 1002 - // Shapes 1084 + /*! \ingroup Shapes 1085 + * @{ */ 1003 1086 1004 1087 /*! Renders a colored point. 1005 1088 * \param target The destination render target ··· 1165 1248 */ 1166 1249 void GPU_PolygonFilled(GPU_Target* target, unsigned int num_vertices, float* vertices, SDL_Color color); 1167 1250 1251 + // End of Shapes 1252 + /*! @} */ 1168 1253 1169 1254 1170 1255 1171 1256 1172 1257 1173 - // Shaders 1258 + /*! \ingroup ShaderInterface 1259 + * @{ */ 1174 1260 1175 1261 /*! Loads shader source from an SDL_RWops, compiles it, and returns the new shader object. */ 1176 1262 Uint32 GPU_CompileShader_RW(GPU_ShaderEnum shader_type, SDL_RWops* shader_source); ··· 1295 1381 /*! Enables a shader attribute and sets its source data. */ 1296 1382 void GPU_SetAttributeSource(int num_values, GPU_Attribute source); 1297 1383 1298 - 1384 + // End of ShaderInterface 1385 + /*! @} */ 1299 1386 1300 1387 1301 1388 #ifdef __cplusplus