eden-emu/SDL
18
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

wikiheaders: Updated to latest, cleaned up category documentation a little.

Browse source 
This documentation needs a LOT of work--maybe someday--but it's definitely not
_broken_ right now, which is good enough for now.
This commit is contained in:
Ryan C. Gordon 2024-05-16 11:41:54 -04:00
parent 96e3799495
commit 1c3a1e1139
No known key found for this signature in database
GPG key ID: FA148B892AB48044
55 changed files with 499 additions and 380 deletions
Download patch file Download diff file Expand all files Collapse all files

4
.wikiheaders-options
View file

@ -19,6 +19,6 @@ wikiheaderfiletext = Defined in [%fname%](https://github.com/libsdl-org/SDL/blob
manpageheaderfiletext = Defined in %fname% manpageheaderfiletext = Defined in %fname%
# All SDL_config_*.h headers are uncategorized, in case something slips in from them. # All SDL_config_*.h headers are uncategorized, in case something slips in from them.
# All SDL_test_* headers become "Test" categories, everything else just converts like SDL_audio.h -> Audio # All SDL_test_* headers become uncategorized, everything else just converts like SDL_audio.h -> Audio
# A handful of others we fix up in the header itself with /* WIKI CATEGORY: x */ comments. # A handful of others we fix up in the header itself with /* WIKI CATEGORY: x */ comments.
headercategoryeval = s/\ASDL_config_.*?\.h\Z//; s/\ASDL_test_.*?\.h\Z/Test/; s/\ASDL_?(.*?)\.h\Z/$1/; ucfirst(); headercategoryeval = s/\ASDL_config_.*?\.h\Z//; s/\ASDL_test_.*?\.h\Z//; s/\ASDL_?(.*?)\.h\Z/$1/; ucfirst();

310
build-scripts/wikiheaders.pl
View file

@ -16,7 +16,7 @@ my $apiprefixregex = undef;
my $versionfname = 'include/SDL_version.h'; my $versionfname = 'include/SDL_version.h';
my $versionmajorregex = '\A\#define\s+SDL_MAJOR_VERSION\s+(\d+)\Z'; my $versionmajorregex = '\A\#define\s+SDL_MAJOR_VERSION\s+(\d+)\Z';
my $versionminorregex = '\A\#define\s+SDL_MINOR_VERSION\s+(\d+)\Z'; my $versionminorregex = '\A\#define\s+SDL_MINOR_VERSION\s+(\d+)\Z';
my $versionpatchregex = '\A\#define\s+SDL_PATCHLEVEL\s+(\d+)\Z'; my $versionmicroregex = '\A\#define\s+SDL_MICRO_VERSION\s+(\d+)\Z';
my $mainincludefname = 'SDL.h'; my $mainincludefname = 'SDL.h';
my $selectheaderregex = '\ASDL.*?\.h\Z'; my $selectheaderregex = '\ASDL.*?\.h\Z';
my $projecturl = 'https://libsdl.org/'; my $projecturl = 'https://libsdl.org/';
@ -92,7 +92,7 @@ if (defined $optionsfname) {
$readmesubdir = $val, next if $key eq 'readmesubdir'; $readmesubdir = $val, next if $key eq 'readmesubdir';
$versionmajorregex = $val, next if $key eq 'versionmajorregex'; $versionmajorregex = $val, next if $key eq 'versionmajorregex';
$versionminorregex = $val, next if $key eq 'versionminorregex'; $versionminorregex = $val, next if $key eq 'versionminorregex';
$versionpatchregex = $val, next if $key eq 'versionpatchregex'; $versionmicroregex = $val, next if $key eq 'versionmicroregex';
$versionfname = $val, next if $key eq 'versionfname'; $versionfname = $val, next if $key eq 'versionfname';
$mainincludefname = $val, next if $key eq 'mainincludefname'; $mainincludefname = $val, next if $key eq 'mainincludefname';
$selectheaderregex = $val, next if $key eq 'selectheaderregex'; $selectheaderregex = $val, next if $key eq 'selectheaderregex';
@ -622,7 +622,7 @@ my %headersymschunk = (); # $headersymschunk{"SDL_OpenAudio"} -> offset in arr
my %headersymshasdoxygen = (); # $headersymshasdoxygen{"SDL_OpenAudio"} -> 1 if there was no existing doxygen for this function. my %headersymshasdoxygen = (); # $headersymshasdoxygen{"SDL_OpenAudio"} -> 1 if there was no existing doxygen for this function.
my %headersymstype = (); # $headersymstype{"SDL_OpenAudio"} -> 1 (function), 2 (macro), 3 (struct), 4 (enum), 5 (other typedef) my %headersymstype = (); # $headersymstype{"SDL_OpenAudio"} -> 1 (function), 2 (macro), 3 (struct), 4 (enum), 5 (other typedef)
my %headersymscategory = (); # $headersymscategory{"SDL_OpenAudio"} -> 'Audio' ... this is set with a `/* WIKI CATEGEORY: Audio */` comment in the headers that sets it on all symbols until a new comment changes it. So usually, once at the top of the header file. my %headersymscategory = (); # $headersymscategory{"SDL_OpenAudio"} -> 'Audio' ... this is set with a `/* WIKI CATEGEORY: Audio */` comment in the headers that sets it on all symbols until a new comment changes it. So usually, once at the top of the header file.
my %headercategorydocs = (); # $headercategorydocs{"Audio"} -> (fake) symbol for this category's documentation. Undefined if not documented.
my %wikitypes = (); # contains string of wiki page extension, like $wikitypes{"SDL_OpenAudio"} == 'mediawiki' my %wikitypes = (); # contains string of wiki page extension, like $wikitypes{"SDL_OpenAudio"} == 'mediawiki'
my %wikisyms = (); # contains references to hash of strings, each string being the full contents of a section of a wiki page, like $wikisyms{"SDL_OpenAudio"}{"Remarks"}. my %wikisyms = (); # contains references to hash of strings, each string being the full contents of a section of a wiki page, like $wikisyms{"SDL_OpenAudio"}{"Remarks"}.
my %wikisectionorder = (); # contains references to array, each array item being a key to a wikipage section in the correct order, like $wikisectionorder{"SDL_OpenAudio"}[2] == 'Remarks' my %wikisectionorder = (); # contains references to array, each array item being a key to a wikipage section in the correct order, like $wikisectionorder{"SDL_OpenAudio"}[2] == 'Remarks'
@ -710,6 +710,7 @@ while (my $d = readdir(DH)) {
my @contents = (); my @contents = ();
my $ignoring_lines = 0; my $ignoring_lines = 0;
my $header_comment = -1; my $header_comment = -1;
my $saw_category_doxygen = -1;
my $lineno = 0; my $lineno = 0;
while (<FH>) { while (<FH>) {
chomp; chomp;
@ -762,6 +763,8 @@ while (my $d = readdir(DH)) {
add_coverage_gap($_, $dent, $lineno) if ($header_comment == 0); add_coverage_gap($_, $dent, $lineno) if ($header_comment == 0);
next; next;
} else { # Start of a doxygen comment, parse it out. } else { # Start of a doxygen comment, parse it out.
my $is_category_doxygen = 0;
@templines = ( $_ ); @templines = ( $_ );
while (<FH>) { while (<FH>) {
chomp; chomp;
@ -783,43 +786,76 @@ while (my $d = readdir(DH)) {
} }
} }
} else { } else {
s/\A\s*\*\s*//; s/\A\s*\*\s*//; # Strip off the " * " at the start of the comment line.
# To add documentation to Category Pages, the rule is it has to
# be the first Doxygen comment in the header, and it must start with `# CategoryX`
# (otherwise we'll treat it as documentation for whatever's below it). `X` is
# the category name, which doesn't _necessarily_ have to match
# $current_wiki_category, but it probably should.
#
# For compatibility with Doxygen, if there's a `\file` here instead of
# `# CategoryName`, we'll accept it and use the $current_wiki_category if set.
if ($saw_category_doxygen == -1) {
$saw_category_doxygen = defined($current_wiki_category) && /\A\\file\s+/;
if ($saw_category_doxygen) {
$_ = "# Category$current_wiki_category";
} else {
$saw_category_doxygen = /\A\# Category/;
}
$is_category_doxygen = $saw_category_doxygen;
}
$str .= "$_\n"; $str .= "$_\n";
} }
} }
$decl = <FH>; if ($is_category_doxygen) {
$lineno++ if defined $decl; $str =~ s/\s*\Z//;
$decl = '' if not defined $decl; $decl = '';
chomp($decl); $symtype = -1; # not a symbol at all.
if ($decl =~ /\A\s*extern\s+(SDL_DEPRECATED\s+|)(SDLMAIN_)?DECLSPEC/) {
$symtype = 1; # function declaration
} elsif ($decl =~ /\A\s*SDL_FORCE_INLINE/) {
$symtype = 1; # (forced-inline) function declaration
} elsif ($decl =~ /\A\s*\#\s*define\s+/) {
$symtype = 2; # macro
} elsif ($decl =~ /\A\s*(typedef\s+|)(struct|union)/) {
$symtype = 3; # struct or union
} elsif ($decl =~ /\A\s*(typedef\s+|)enum/) {
$symtype = 4; # enum
} elsif ($decl =~ /\A\s*typedef\s+.*\Z/) {
$symtype = 5; # other typedef
} else { } else {
#print "Found doxygen but no function sig:\n$str\n\n"; $decl = <FH>;
foreach (@templines) { $lineno++ if defined $decl;
push @contents, $_; $decl = '' if not defined $decl;
add_coverage_gap($_, $dent, $lineno); chomp($decl);
if ($decl =~ /\A\s*extern\s+(SDL_DEPRECATED\s+|)(SDLMAIN_)?DECLSPEC/) {
$symtype = 1; # function declaration
} elsif ($decl =~ /\A\s*SDL_FORCE_INLINE/) {
$symtype = 1; # (forced-inline) function declaration
} elsif ($decl =~ /\A\s*\#\s*define\s+/) {
$symtype = 2; # macro
} elsif ($decl =~ /\A\s*(typedef\s+|)(struct|union)/) {
$symtype = 3; # struct or union
} elsif ($decl =~ /\A\s*(typedef\s+|)enum/) {
$symtype = 4; # enum
} elsif ($decl =~ /\A\s*typedef\s+.*\Z/) {
$symtype = 5; # other typedef
} else {
#print "Found doxygen but no function sig:\n$str\n\n";
foreach (@templines) {
push @contents, $_;
add_coverage_gap($_, $dent, $lineno);
}
push @contents, $decl;
add_coverage_gap($decl, $dent, $lineno);
next;
} }
push @contents, $decl;
add_coverage_gap($decl, $dent, $lineno);
next;
} }
} }
my @decllines = ( $decl ); my @decllines = ( $decl );
my $sym = ''; my $sym = '';
if ($symtype == 1) { # a function if ($symtype == -1) { # category documentation with no symbol attached.
@decllines = ();
if ($str =~ /^#\s*Category(.*?)\s*$/m) {
$sym = "[category documentation] $1"; # make a fake, unique symbol that's not valid C.
} else {
die("Unexpected category documentation line '$str' in '$incpath/$dent' ...?");
}
$headercategorydocs{$current_wiki_category} = $sym;
} elsif ($symtype == 1) { # a function
my $is_forced_inline = ($decl =~ /\A\s*SDL_FORCE_INLINE/); my $is_forced_inline = ($decl =~ /\A\s*SDL_FORCE_INLINE/);
if ($is_forced_inline) { if ($is_forced_inline) {
@ -1128,7 +1164,7 @@ while (my $d = readdir(DH)) {
if ($has_doxygen) { if ($has_doxygen) {
print STDERR "WARNING: Symbol '$sym' appears to be documented in multiple locations. Only keeping the first one we saw!\n"; print STDERR "WARNING: Symbol '$sym' appears to be documented in multiple locations. Only keeping the first one we saw!\n";
} }
push @contents, join("\n", @decllines); # just put the existing declation in as-is. push @contents, join("\n", @decllines) if (scalar(@decllines) > 0); # just put the existing declation in as-is.
} }
} }
@ -1141,7 +1177,7 @@ while (my $d = readdir(DH)) {
$headersymshasdoxygen{$sym} = $has_doxygen; $headersymshasdoxygen{$sym} = $has_doxygen;
$headersymstype{$sym} = $symtype; $headersymstype{$sym} = $symtype;
push @contents, join("\n", @templines); push @contents, join("\n", @templines);
push @contents, join("\n", @decllines); push @contents, join("\n", @decllines) if (scalar(@decllines) > 0);
} }
} }
@ -1168,11 +1204,41 @@ while (my $d = readdir(DH)) {
# Ignore FrontPage. # Ignore FrontPage.
next if $sym eq 'FrontPage'; next if $sym eq 'FrontPage';
# Ignore "Category*" pages.
next if ($sym =~ /\ACategory/);
open(FH, '<', "$wikipath/$dent") or die("Can't open '$wikipath/$dent': $!\n"); open(FH, '<', "$wikipath/$dent") or die("Can't open '$wikipath/$dent': $!\n");
if ($sym =~ /\ACategory(.*?)\Z/) { # Special case for Category pages.
# Find the end of the category documentation in the existing file and append everything else to the new file.
my $cat = $1;
my $docstr = '';
my $notdocstr = '';
my $docs = 1;
while (<FH>) {
chomp;
if ($docs) {
$docs = 0 if /\A\-\-\-\-\Z/; # Hit a footer? We're done.
$docs = 0 if /\A<!\-\-/; # Hit an HTML comment? We're done.
}
if ($docs) {
$docstr .= "$_\n";
} else {
$notdocstr .= "$_\n";
}
}
close(FH);
$docstr =~ s/\s*\Z//;
$sym = "[category documentation] $cat"; # make a fake, unique symbol that's not valid C.
$wikitypes{$sym} = $type;
my %sections = ();
$sections{'Remarks'} = $docstr;
$sections{'[footer]'} = $notdocstr;
$wikisyms{$sym} = \%sections;
my @section_order = ( 'Remarks', '[footer]' );
$wikisectionorder{$sym} = \@section_order;
next;
}
my $current_section = '[start]'; my $current_section = '[start]';
my @section_order = ( $current_section ); my @section_order = ( $current_section );
my %sections = (); my %sections = ();
@ -1325,7 +1391,9 @@ if ($copy_direction == 1) { # --copy-to-headers
my $params = undef; my $params = undef;
my $paramstr = undef; my $paramstr = undef;
if (($symtype == 1) || (($symtype == 5))) { # we'll assume a typedef (5) with a \param is a function pointer typedef. if ($symtype == -1) { # category documentation block.
# nothing to be done here.
} elsif (($symtype == 1) || (($symtype == 5))) { # we'll assume a typedef (5) with a \param is a function pointer typedef.
$params = $sectionsref->{'Function Parameters'}; $params = $sectionsref->{'Function Parameters'};
$paramstr = '\param'; $paramstr = '\param';
} elsif ($symtype == 2) { } elsif ($symtype == 2) {
@ -1520,7 +1588,7 @@ if ($copy_direction == 1) { # --copy-to-headers
} }
$output .= " */"; $output .= " */";
#print("$sym:\n$output\n\n"); #print("$sym:\n[$output]\n\n");
$$contentsref[$chunk] = $output; $$contentsref[$chunk] = $output;
#$$contentsref[$chunk+1] = $headerdecls{$sym}; #$$contentsref[$chunk+1] = $headerdecls{$sym};
@ -1569,6 +1637,7 @@ if ($copy_direction == 1) { # --copy-to-headers
closedir(DH); closedir(DH);
} }
} }
} elsif ($copy_direction == -1) { # --copy-to-wiki } elsif ($copy_direction == -1) { # --copy-to-wiki
if (defined $changeformat) { if (defined $changeformat) {
@ -1579,6 +1648,7 @@ if ($copy_direction == 1) { # --copy-to-headers
foreach (keys %headersyms) { foreach (keys %headersyms) {
my $sym = $_; my $sym = $_;
next if not $headersymshasdoxygen{$sym}; next if not $headersymshasdoxygen{$sym};
next if $sym =~ /\A\[category documentation\]/; # not real symbols, we handle this elsewhere.
my $symtype = $headersymstype{$sym}; my $symtype = $headersymstype{$sym};
my $origwikitype = defined $wikitypes{$sym} ? $wikitypes{$sym} : 'md'; # default to MarkDown for new stuff. my $origwikitype = defined $wikitypes{$sym} ? $wikitypes{$sym} : 'md'; # default to MarkDown for new stuff.
my $wikitype = (defined $changeformat) ? $changeformat : $origwikitype; my $wikitype = (defined $changeformat) ? $changeformat : $origwikitype;
@ -1812,7 +1882,7 @@ if ($copy_direction == 1) { # --copy-to-headers
$sections{'Function Parameters'} = $str; $sections{'Function Parameters'} = $str;
} }
my $path = "$wikipath/$_.${wikitype}.tmp"; my $path = "$wikipath/$sym.${wikitype}.tmp";
open(FH, '>', $path) or die("Can't open '$path': $!\n"); open(FH, '>', $path) or die("Can't open '$path': $!\n");
my $sectionsref = $wikisyms{$sym}; my $sectionsref = $wikisyms{$sym};
@ -1848,44 +1918,46 @@ if ($copy_direction == 1) { # --copy-to-headers
} }
} }
my $footer = $$sectionsref{'[footer]'}; if ($symtype != -1) { # Don't do these in category documentation block
my $footer = $$sectionsref{'[footer]'};
my $symtypename; my $symtypename;
if ($symtype == 1) { if ($symtype == 1) {
$symtypename = 'Function'; $symtypename = 'Function';
} elsif ($symtype == 2) { } elsif ($symtype == 2) {
$symtypename = 'Macro'; $symtypename = 'Macro';
} elsif ($symtype == 3) { } elsif ($symtype == 3) {
$symtypename = 'Struct'; $symtypename = 'Struct';
} elsif ($symtype == 4) { } elsif ($symtype == 4) {
$symtypename = 'Enum'; $symtypename = 'Enum';
} elsif ($symtype == 5) { } elsif ($symtype == 5) {
$symtypename = 'Datatype'; $symtypename = 'Datatype';
} else { } else {
die("Unexpected symbol type $symtype!"); die("Unexpected symbol type $symtype!");
} }
my $symcategory = $headersymscategory{$sym}; my $symcategory = $headersymscategory{$sym};
if ($wikitype eq 'mediawiki') {
$footer =~ s/\[\[CategoryAPI\]\],?\s*//g;
$footer =~ s/\[\[CategoryAPI${symtypename}\]\],?\s*//g;
$footer =~ s/\[\[Category${symcategory}\]\],?\s*//g if defined $symcategory;
$footer = "[[CategoryAPI]], [[CategoryAPI$symtypename]]" . (defined $symcategory ? ", [[Category$symcategory]]" : '') . (($footer eq '') ? "\n" : ", $footer");
} elsif ($wikitype eq 'md') {
$footer =~ s/\[CategoryAPI\]\(CategoryAPI\),?\s*//g;
$footer =~ s/\[CategoryAPI${symtypename}\]\(CategoryAPI${symtypename}\),?\s*//g;
$footer =~ s/\[Category${symcategory}\]\(Category${symcategory}\),?\s*//g if defined $symcategory;
$footer = "[CategoryAPI](CategoryAPI), [CategoryAPI$symtypename](CategoryAPI$symtypename)" . (defined $symcategory ? ", [Category$symcategory](Category$symcategory)" : '') . (($footer eq '') ? '' : ', ') . $footer;
} else { die("Unexpected wikitype '$wikitype'"); }
$$sectionsref{'[footer]'} = $footer;
if (defined $wikipreamble) {
my $wikified_preamble = wikify($wikitype, $wikipreamble);
if ($wikitype eq 'mediawiki') { if ($wikitype eq 'mediawiki') {
print FH "====== $wikified_preamble ======\n"; $footer =~ s/\[\[CategoryAPI\]\],?\s*//g;
$footer =~ s/\[\[CategoryAPI${symtypename}\]\],?\s*//g;
$footer =~ s/\[\[Category${symcategory}\]\],?\s*//g if defined $symcategory;
$footer = "[[CategoryAPI]], [[CategoryAPI$symtypename]]" . (defined $symcategory ? ", [[Category$symcategory]]" : '') . (($footer eq '') ? "\n" : ", $footer");
} elsif ($wikitype eq 'md') { } elsif ($wikitype eq 'md') {
print FH "###### $wikified_preamble\n"; $footer =~ s/\[CategoryAPI\]\(CategoryAPI\),?\s*//g;
$footer =~ s/\[CategoryAPI${symtypename}\]\(CategoryAPI${symtypename}\),?\s*//g;
$footer =~ s/\[Category${symcategory}\]\(Category${symcategory}\),?\s*//g if defined $symcategory;
$footer = "[CategoryAPI](CategoryAPI), [CategoryAPI$symtypename](CategoryAPI$symtypename)" . (defined $symcategory ? ", [Category$symcategory](Category$symcategory)" : '') . (($footer eq '') ? '' : ', ') . $footer;
} else { die("Unexpected wikitype '$wikitype'"); } } else { die("Unexpected wikitype '$wikitype'"); }
$$sectionsref{'[footer]'} = $footer;
if (defined $wikipreamble) {
my $wikified_preamble = wikify($wikitype, $wikipreamble);
if ($wikitype eq 'mediawiki') {
print FH "====== $wikified_preamble ======\n";
} elsif ($wikitype eq 'md') {
print FH "###### $wikified_preamble\n";
} else { die("Unexpected wikitype '$wikitype'"); }
}
} }
my $prevsectstr = ''; my $prevsectstr = '';
@ -1925,11 +1997,13 @@ if ($copy_direction == 1) { # --copy-to-headers
} }
} }
if ($wikitype eq 'mediawiki') { if ($symtype != -1) { # Not for category documentation block
print FH "\n== $sectname ==\n\n"; if ($wikitype eq 'mediawiki') {
} elsif ($wikitype eq 'md') { print FH "\n== $sectname ==\n\n";
print FH "\n## $sectname\n\n"; } elsif ($wikitype eq 'md') {
} else { die("Unexpected wikitype '$wikitype'"); } print FH "\n## $sectname\n\n";
} else { die("Unexpected wikitype '$wikitype'"); }
}
} }
my $sectstr = defined $sections{$sect} ? $sections{$sect} : $$sectionsref{$sect}; my $sectstr = defined $sections{$sect} ? $sections{$sect} : $$sectionsref{$sect};
@ -1973,6 +2047,74 @@ if ($copy_direction == 1) { # --copy-to-headers
close(FH); close(FH);
} }
# Write out Category pages...
foreach (keys %headercategorydocs) {
my $cat = $_;
my $sym = $headercategorydocs{$cat}; # fake symbol
my $raw = $headersyms{$sym}; # raw doxygen text with comment characters stripped from start/end and start of each line.
my $wikitype = defined($wikitypes{$sym}) ? $wikitypes{$sym} : 'md';
my $path = "$wikipath/Category$cat.$wikitype";
$raw = wordwrap(wikify($wikitype, $raw));
my $tmppath = "$path.tmp";
open(FH, '>', $tmppath) or die("Can't open '$tmppath': $!\n");
print FH "$raw\n\n";
if (! -f $path) { # Doesn't exist at all? Write out a template file.
# If writing from scratch, it's always a Markdown file.
die("Unexpected wikitype '$wikitype'!") if $wikitype ne 'md';
print FH <<__EOF__
<!-- END CATEGORY DOCUMENTATION -->
## Functions
<!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. -->
<!-- BEGIN CATEGORY LIST: Category$cat, CategoryAPIFunction -->
<!-- END CATEGORY LIST -->
## Datatypes
<!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. -->
<!-- BEGIN CATEGORY LIST: Category$cat, CategoryAPIDatatype -->
<!-- END CATEGORY LIST -->
## Structs
<!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. -->
<!-- BEGIN CATEGORY LIST: Category$cat, CategoryAPIStruct -->
<!-- END CATEGORY LIST -->
## Enums
<!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. -->
<!-- BEGIN CATEGORY LIST: Category$cat, CategoryAPIEnum -->
<!-- END CATEGORY LIST -->
## Macros
<!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. -->
<!-- BEGIN CATEGORY LIST: Category$cat, CategoryAPIMacro -->
<!-- END CATEGORY LIST -->
----
[CategoryAPICategory](CategoryAPICategory)
__EOF__
;
} else {
my $endstr = $wikisyms{$sym}->{'[footer]'};
if (defined($endstr)) {
print FH $endstr;
}
}
close(FH);
rename($tmppath, $path) or die("Can't rename '$tmppath' to '$path': $!\n");
}
# Write out READMEs...
if (defined $readmepath) { if (defined $readmepath) {
if ( -d $readmepath ) { if ( -d $readmepath ) {
mkdir($wikireadmepath); # just in case mkdir($wikireadmepath); # just in case
@ -2036,23 +2178,24 @@ if ($copy_direction == 1) { # --copy-to-headers
open(FH, '<', "$srcpath/$versionfname") or die("Can't open '$srcpath/$versionfname': $!\n"); open(FH, '<', "$srcpath/$versionfname") or die("Can't open '$srcpath/$versionfname': $!\n");
my $majorver = 0; my $majorver = 0;
my $minorver = 0; my $minorver = 0;
my $patchver = 0; my $microver = 0;
while (<FH>) { while (<FH>) {
chomp; chomp;
if (/$versionmajorregex/) { if (/$versionmajorregex/) {
$majorver = int($1); $majorver = int($1);
} elsif (/$versionminorregex/) { } elsif (/$versionminorregex/) {
$minorver = int($1); $minorver = int($1);
} elsif (/$versionpatchregex/) { } elsif (/$versionmicroregex/) {
$patchver = int($1); $microver = int($1);
} }
} }
close(FH); close(FH);
my $fullversion = "$majorver.$minorver.$patchver"; my $fullversion = "$majorver.$minorver.$microver";
foreach (keys %headersyms) { foreach (keys %headersyms) {
my $sym = $_; my $sym = $_;
next if not defined $wikisyms{$sym}; # don't have a page for that function, skip it. next if not defined $wikisyms{$sym}; # don't have a page for that function, skip it.
next if $sym =~ /\A\[category documentation\]/; # not real symbols
my $symtype = $headersymstype{$sym}; my $symtype = $headersymstype{$sym};
my $wikitype = $wikitypes{$sym}; my $wikitype = $wikitypes{$sym};
my $sectionsref = $wikisyms{$sym}; my $sectionsref = $wikisyms{$sym};
@ -2318,19 +2461,19 @@ if ($copy_direction == 1) { # --copy-to-headers
open(FH, '<', "$srcpath/$versionfname") or die("Can't open '$srcpath/$versionfname': $!\n"); open(FH, '<', "$srcpath/$versionfname") or die("Can't open '$srcpath/$versionfname': $!\n");
my $majorver = 0; my $majorver = 0;
my $minorver = 0; my $minorver = 0;
my $patchver = 0; my $microver = 0;
while (<FH>) { while (<FH>) {
chomp; chomp;
if (/$versionmajorregex/) { if (/$versionmajorregex/) {
$majorver = int($1); $majorver = int($1);
} elsif (/$versionminorregex/) { } elsif (/$versionminorregex/) {
$minorver = int($1); $minorver = int($1);
} elsif (/$versionpatchregex/) { } elsif (/$versionmicroregex/) {
$patchver = int($1); $microver = int($1);
} }
} }
close(FH); close(FH);
my $fullversion = "$majorver.$minorver.$patchver"; my $fullversion = "$majorver.$minorver.$microver";
my $latex_fname = "$srcpath/$projectshortname.tex"; my $latex_fname = "$srcpath/$projectshortname.tex";
my $latex_tmpfname = "$latex_fname.tmp"; my $latex_tmpfname = "$latex_fname.tmp";
@ -2369,7 +2512,7 @@ if ($copy_direction == 1) { # --copy-to-headers
\\begin{document} \\begin{document}
\\frontmatter \\frontmatter
\\title{$projectfullname $majorver.$minorver.$patchver Reference Manual} \\title{$projectfullname $majorver.$minorver.$microver Reference Manual}
\\author{The $projectshortname Developers} \\author{The $projectshortname Developers}
\\maketitle \\maketitle
@ -2399,6 +2542,7 @@ __EOF__
foreach (@headersymskeys) { foreach (@headersymskeys) {
my $sym = $_; my $sym = $_;
next if not defined $wikisyms{$sym}; # don't have a page for that function, skip it. next if not defined $wikisyms{$sym}; # don't have a page for that function, skip it.
next if $sym =~ /\A\[category documentation\]/; # not real symbols.
my $symtype = $headersymstype{$sym}; my $symtype = $headersymstype{$sym};
my $wikitype = $wikitypes{$sym}; my $wikitype = $wikitypes{$sym};
my $sectionsref = $wikisyms{$sym}; my $sectionsref = $wikisyms{$sym};

39
include/SDL_atomic.h
View file

@ -20,38 +20,29 @@
*/ */
/** /**
* \file SDL_atomic.h * # CategoryAtomic
* *
* Atomic operations. * Atomic operations.
* *
* IMPORTANT: * IMPORTANT: If you are not an expert in concurrent lockless programming, you
* If you are not an expert in concurrent lockless programming, you should * should not be using any functions in this file. You should be protecting
* only be using the atomic lock and reference counting functions in this * your data structures with full mutexes instead.
* file. In all other cases you should be protecting your data structures
* with full mutexes.
* *
* The list of "safe" functions to use are: * ***Seriously, here be dragons!***
* SDL_AtomicLock()
* SDL_AtomicUnlock()
* SDL_AtomicIncRef()
* SDL_AtomicDecRef()
* *
* Seriously, here be dragons! * You can find out a little more about lockless programming and the subtle
* ^^^^^^^^^^^^^^^^^^^^^^^^^^^ * issues that can arise here:
* * https://learn.microsoft.com/en-us/windows/win32/dxtecharts/lockless-programming
* You can find out a little more about lockless programming and the
* subtle issues that can arise here:
* http://msdn.microsoft.com/en-us/library/ee418650%28v=vs.85%29.aspx
* *
* There's also lots of good information here: * There's also lots of good information here:
* http://www.1024cores.net/home/lock-free-algorithms
* http://preshing.com/
* *
* These operations may or may not actually be implemented using * - https://www.1024cores.net/home/lock-free-algorithms
* processor specific atomic operations. When possible they are * - https://preshing.com/
* implemented as true processor specific atomic operations. When that *
* is not possible the are implemented using locks that *do* use the * These operations may or may not actually be implemented using processor
* available atomic operations. * specific atomic operations. When possible they are implemented as true
* processor specific atomic operations. When that is not possible the are
* implemented using locks that *do* use the available atomic operations.
* *
* All of the atomic operations that modify memory are full memory barriers. * All of the atomic operations that modify memory are full memory barriers.
*/ */

4
include/SDL_audio.h
View file

@ -22,9 +22,9 @@
/* !!! FIXME: several functions in here need Doxygen comments. */ /* !!! FIXME: several functions in here need Doxygen comments. */
/** /**
* \file SDL_audio.h * # CategoryAudio
* *
* Access to the raw audio mixing buffer for the SDL library. * Access to the raw audio mixing buffer for the SDL library.
*/ */
#ifndef SDL_audio_h_ #ifndef SDL_audio_h_

4
include/SDL_bits.h
View file

@ -20,9 +20,9 @@
*/ */
/** /**
* \file SDL_bits.h * # CategoryBits
* *
* Functions for fiddling with bits and bitmasks. * Functions for fiddling with bits and bitmasks.
*/ */
#ifndef SDL_bits_h_ #ifndef SDL_bits_h_

4
include/SDL_blendmode.h
View file

@ -20,9 +20,9 @@
*/ */
/** /**
* \file SDL_blendmode.h * # CategoryBlendmode
* *
* Header file declaring the SDL_BlendMode enumeration * Header file declaring the SDL_BlendMode enumeration
*/ */
#ifndef SDL_blendmode_h_ #ifndef SDL_blendmode_h_

2
include/SDL_clipboard.h
View file

@ -20,7 +20,7 @@
*/ */
/** /**
* \file SDL_clipboard.h * # CategoryClipboard
* *
* Include file for SDL clipboard handling * Include file for SDL clipboard handling
*/ */

4
include/SDL_config.h
View file

@ -24,9 +24,7 @@
#include "SDL_platform.h" #include "SDL_platform.h"
/** /* WIKI CATEGORY: - */
* \file SDL_config.h
*/
/* Add any platform that doesn't build using the configure system. */ /* Add any platform that doesn't build using the configure system. */
#if defined(__WIN32__) #if defined(__WIN32__)

12
include/SDL_cpuinfo.h
View file

@ -19,10 +19,16 @@
3. This notice may not be removed or altered from any source distribution. 3. This notice may not be removed or altered from any source distribution.
*/ */
/* WIKI CATEGORY: CPUInfo */
/** /**
* \file SDL_cpuinfo.h * # CategoryCPUInfo
* *
* CPU feature detection for SDL. * CPU feature detection for SDL.
*
* These functions are largely concerned with reporting if the system has
* access to various SIMD instruction sets, but also has other important info
* to share, such as number of logical CPU cores.
*/ */
#ifndef SDL_cpuinfo_h_ #ifndef SDL_cpuinfo_h_
@ -30,8 +36,6 @@
#include "SDL_stdinc.h" #include "SDL_stdinc.h"
/* WIKI CATEGORY: CPUInfo */
/* Need to do this here because intrin.h has C++ code in it */ /* Need to do this here because intrin.h has C++ code in it */
/* Visual Studio 2005 has a bug where intrin.h conflicts with winnt.h */ /* Visual Studio 2005 has a bug where intrin.h conflicts with winnt.h */
#if defined(_MSC_VER) && (_MSC_VER >= 1500) && (defined(_M_IX86) || defined(_M_X64)) #if defined(_MSC_VER) && (_MSC_VER >= 1500) && (defined(_M_IX86) || defined(_M_X64))

7
include/SDL_egl.h
View file

@ -19,11 +19,10 @@
3. This notice may not be removed or altered from any source distribution. 3. This notice may not be removed or altered from any source distribution.
*/ */
/** /*
* \file SDL_egl.h * This is a simple file to encapsulate the EGL API headers.
*
* This is a simple file to encapsulate the EGL API headers.
*/ */
#if !defined(_MSC_VER) && !defined(__ANDROID__) && !defined(SDL_USE_BUILTIN_OPENGL_DEFINITIONS) #if !defined(_MSC_VER) && !defined(__ANDROID__) && !defined(SDL_USE_BUILTIN_OPENGL_DEFINITIONS)
#if defined(__vita__) || defined(__psp2__) #if defined(__vita__) || defined(__psp2__)

4
include/SDL_endian.h
View file

@ -20,9 +20,9 @@
*/ */
/** /**
* \file SDL_endian.h * # CategoryEndian
* *
* Functions for reading and writing endian-specific values * Functions for reading and writing endian-specific values
*/ */
#ifndef SDL_endian_h_ #ifndef SDL_endian_h_

4
include/SDL_error.h
View file

@ -20,9 +20,9 @@
*/ */
/** /**
* \file SDL_error.h * # CategoryError
* *
* Simple error message routines for SDL. * Simple error message routines for SDL.
*/ */
#ifndef SDL_error_h_ #ifndef SDL_error_h_

4
include/SDL_events.h
View file

@ -20,9 +20,9 @@
*/ */
/** /**
* \file SDL_events.h * # CategoryEvents
* *
* Include file for SDL event handling. * Include file for SDL event handling.
*/ */
#ifndef SDL_events_h_ #ifndef SDL_events_h_

4
include/SDL_filesystem.h
View file

@ -20,9 +20,9 @@
*/ */
/** /**
* \file SDL_filesystem.h * # CategoryFilesystem
* *
* \brief Include file for filesystem SDL API functions * Include file for filesystem SDL API functions
*/ */
#ifndef SDL_filesystem_h_ #ifndef SDL_filesystem_h_

12
include/SDL_gamecontroller.h
View file

@ -19,14 +19,14 @@
3. This notice may not be removed or altered from any source distribution. 3. This notice may not be removed or altered from any source distribution.
*/ */
/**
* \file SDL_gamecontroller.h
*
* Include file for SDL game controller event handling
*/
/* WIKI CATEGORY: GameController */ /* WIKI CATEGORY: GameController */
/**
* # CategoryGameController
*
* Include file for SDL game controller event handling
*/
#ifndef SDL_gamecontroller_h_ #ifndef SDL_gamecontroller_h_
#define SDL_gamecontroller_h_ #define SDL_gamecontroller_h_

4
include/SDL_gesture.h
View file

@ -20,9 +20,9 @@
*/ */
/** /**
* \file SDL_gesture.h * # CategoryGesture
* *
* Include file for SDL gesture event handling. * Include file for SDL gesture event handling.
*/ */
#ifndef SDL_gesture_h_ #ifndef SDL_gesture_h_

13
include/SDL_guid.h
View file

@ -19,14 +19,15 @@
3. This notice may not be removed or altered from any source distribution. 3. This notice may not be removed or altered from any source distribution.
*/ */
/**
* \file SDL_guid.h
*
* Include file for handling SDL_GUID values.
*/
/* WIKI CATEGORY: GUID */ /* WIKI CATEGORY: GUID */
/**
* # CategoryGUID
*
* A GUID is a 128-bit value that represents something that is uniquely
* identifiable by this value: "globally unique."
*/
#ifndef SDL_guid_h_ #ifndef SDL_guid_h_
#define SDL_guid_h_ #define SDL_guid_h_

28
include/SDL_haptic.h
View file

@ -20,23 +20,23 @@
*/ */
/** /**
* \file SDL_haptic.h * # CategoryHaptic
* *
* \brief The SDL haptic subsystem allows you to control haptic (force feedback) * SDL haptic subsystem allows you to control haptic (force feedback) devices.
* devices.
* *
* The basic usage is as follows: * The basic usage is as follows:
* - Initialize the subsystem (SDL_INIT_HAPTIC).
* - Open a haptic device.
* - SDL_HapticOpen() to open from index.
* - SDL_HapticOpenFromJoystick() to open from an existing joystick.
* - Create an effect (SDL_HapticEffect).
* - Upload the effect with SDL_HapticNewEffect().
* - Run the effect with SDL_HapticRunEffect().
* - (optional) Free the effect with SDL_HapticDestroyEffect().
* - Close the haptic device with SDL_HapticClose().
* *
* \par Simple rumble example: * - Initialize the subsystem (SDL_INIT_HAPTIC).
* - Open a haptic device.
* - SDL_HapticOpen() to open from index.
* - SDL_HapticOpenFromJoystick() to open from an existing joystick.
* - Create an effect (SDL_HapticEffect).
* - Upload the effect with SDL_HapticNewEffect().
* - Run the effect with SDL_HapticRunEffect().
* - (optional) Free the effect with SDL_HapticDestroyEffect().
* - Close the haptic device with SDL_HapticClose().
*
* Simple rumble example:
* *
* ```c * ```c
* SDL_Haptic *haptic; * SDL_Haptic *haptic;

71
include/SDL_hidapi.h
View file

@ -19,48 +19,51 @@
3. This notice may not be removed or altered from any source distribution. 3. This notice may not be removed or altered from any source distribution.
*/ */
/* WIKI CATEGORY: HIDAPI */
/** /**
* \file SDL_hidapi.h * # CategoryHIDAPI
* *
* Header file for SDL HIDAPI functions. * Header file for SDL HIDAPI functions.
* *
* This is an adaptation of the original HIDAPI interface by Alan Ott, * This is an adaptation of the original HIDAPI interface by Alan Ott, and
* and includes source code licensed under the following BSD license: * includes source code licensed under the following BSD license:
* *
Copyright (c) 2010, Alan Ott, Signal 11 Software * ```
All rights reserved. * Copyright (c) 2010, Alan Ott, Signal 11 Software
* All rights reserved.
Redistribution and use in source and binary forms, with or without *
modification, are permitted provided that the following conditions are met: * Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice, *
this list of conditions and the following disclaimer. * * Redistributions of source code must retain the above copyright notice,
* Redistributions in binary form must reproduce the above copyright * this list of conditions and the following disclaimer.
notice, this list of conditions and the following disclaimer in the * * Redistributions in binary form must reproduce the above copyright
documentation and/or other materials provided with the distribution. * notice, this list of conditions and the following disclaimer in the
* Neither the name of Signal 11 Software nor the names of its * documentation and/or other materials provided with the distribution.
contributors may be used to endorse or promote products derived from * * Neither the name of Signal 11 Software nor the names of its
this software without specific prior written permission. * contributors may be used to endorse or promote products derived from
* this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" *
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
POSSIBILITY OF SUCH DAMAGE. * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
* POSSIBILITY OF SUCH DAMAGE.
* ```
* *
* If you would like a version of SDL without this code, you can build SDL * If you would like a version of SDL without this code, you can build SDL
* with SDL_HIDAPI_DISABLED defined to 1. You might want to do this for example * with SDL_HIDAPI_DISABLED defined to 1. You might want to do this for
* on iOS or tvOS to avoid a dependency on the CoreBluetooth framework. * example on iOS or tvOS to avoid a dependency on the CoreBluetooth
* framework.
*/ */
/* WIKI CATEGORY: HIDAPI */
#ifndef SDL_hidapi_h_ #ifndef SDL_hidapi_h_
#define SDL_hidapi_h_ #define SDL_hidapi_h_

20
include/SDL_hints.h
View file

@ -20,20 +20,20 @@
*/ */
/** /**
* \file SDL_hints.h * # CategoryHints
* *
* Official documentation for SDL configuration variables * Official documentation for SDL configuration variables
* *
* This file contains functions to set and get configuration hints, * This file contains functions to set and get configuration hints, as well as
* as well as listing each of them alphabetically. * listing each of them alphabetically.
* *
* The convention for naming hints is SDL_HINT_X, where "SDL_X" is * The convention for naming hints is SDL_HINT_X, where "SDL_X" is the
* the environment variable that can be used to override the default. * environment variable that can be used to override the default.
* *
* In general these hints are just that - they may or may not be * In general these hints are just that - they may or may not be supported or
* supported or applicable on any given platform, but they provide * applicable on any given platform, but they provide a way for an application
* a way for an application or user to give the library a hint as * or user to give the library a hint as to how they would like the library to
* to how they would like the library to work. * work.
*/ */
#ifndef SDL_hints_h_ #ifndef SDL_hints_h_

24
include/SDL_joystick.h
View file

@ -20,22 +20,26 @@
*/ */
/** /**
* \file SDL_joystick.h * # CategoryJoystick
* *
* Include file for SDL joystick event handling * Include file for SDL joystick event handling
* *
* The term "device_index" identifies currently plugged in joystick devices between 0 and SDL_NumJoysticks(), with the exact joystick * The term "device_index" identifies currently plugged in joystick devices
* behind a device_index changing as joysticks are plugged and unplugged. * between 0 and SDL_NumJoysticks(), with the exact joystick behind a
* device_index changing as joysticks are plugged and unplugged.
* *
* The term "instance_id" is the current instantiation of a joystick device in the system, if the joystick is removed and then re-inserted * The term "instance_id" is the current instantiation of a joystick device in
* then it will get a new instance_id, instance_id's are monotonically increasing identifiers of a joystick plugged in. * the system, if the joystick is removed and then re-inserted then it will
* get a new instance_id, instance_id's are monotonically increasing
* identifiers of a joystick plugged in.
* *
* The term "player_index" is the number assigned to a player on a specific * The term "player_index" is the number assigned to a player on a specific
* controller. For XInput controllers this returns the XInput user index. * controller. For XInput controllers this returns the XInput user index. Many
* Many joysticks will not be able to supply this information. * joysticks will not be able to supply this information.
* *
* The term JoystickGUID is a stable 128-bit identifier for a joystick device that does not change over time, it identifies class of * The term JoystickGUID is a stable 128-bit identifier for a joystick device
* the device (a X360 wired controller for example). This identifier is platform dependent. * that does not change over time, it identifies class of the device (a X360
* wired controller for example). This identifier is platform dependent.
*/ */
#ifndef SDL_joystick_h_ #ifndef SDL_joystick_h_

4
include/SDL_keyboard.h
View file

@ -20,9 +20,9 @@
*/ */
/** /**
* \file SDL_keyboard.h * # CategoryKeyboard
* *
* Include file for SDL keyboard event handling * Include file for SDL keyboard event handling
*/ */
#ifndef SDL_keyboard_h_ #ifndef SDL_keyboard_h_

4
include/SDL_keycode.h
View file

@ -20,9 +20,9 @@
*/ */
/** /**
* \file SDL_keycode.h * # CategoryKeycode
* *
* Defines constants which identify keyboard keys and modifiers. * Defines constants which identify keyboard keys and modifiers.
*/ */
#ifndef SDL_keycode_h_ #ifndef SDL_keycode_h_

38
include/SDL_loadso.h
View file

@ -19,27 +19,27 @@
3. This notice may not be removed or altered from any source distribution. 3. This notice may not be removed or altered from any source distribution.
*/ */
/**
* \file SDL_loadso.h
*
* System dependent library loading routines
*
* Some things to keep in mind:
* \li These functions only work on C function names. Other languages may
* have name mangling and intrinsic language support that varies from
* compiler to compiler.
* \li Make sure you declare your function pointers with the same calling
* convention as the actual library function. Your code will crash
* mysteriously if you do not do this.
* \li Avoid namespace collisions. If you load a symbol from the library,
* it is not defined whether or not it goes into the global symbol
* namespace for the application. If it does and it conflicts with
* symbols in your code or other shared libraries, you will not get
* the results you expect. :)
*/
/* WIKI CATEGORY: LoadSO */ /* WIKI CATEGORY: LoadSO */
/**
* # CategoryLoadSO
*
* System-dependent library loading routines.
*
* Some things to keep in mind:
*
* - These functions only work on C function names. Other languages may have
* name mangling and intrinsic language support that varies from compiler to
* compiler.
* - Make sure you declare your function pointers with the same calling
* convention as the actual library function. Your code will crash
* mysteriously if you do not do this.
* - Avoid namespace collisions. If you load a symbol from the library, it is
* not defined whether or not it goes into the global symbol namespace for
* the application. If it does and it conflicts with symbols in your code or
* other shared libraries, you will not get the results you expect. :)
*/
#ifndef SDL_loadso_h_ #ifndef SDL_loadso_h_
#define SDL_loadso_h_ #define SDL_loadso_h_

4
include/SDL_locale.h
View file

@ -20,9 +20,9 @@
*/ */
/** /**
* \file SDL_locale.h * # CategoryLocale
* *
* Include file for SDL locale services * Include file for SDL locale services
*/ */
#ifndef _SDL_locale_h #ifndef _SDL_locale_h

17
include/SDL_log.h
View file

@ -20,18 +20,19 @@
*/ */
/** /**
* \file SDL_log.h * # CategoryLog
* *
* Simple log messages with categories and priorities. * Simple log messages with categories and priorities.
* *
* By default logs are quiet, but if you're debugging SDL you might want: * By default logs are quiet, but if you're debugging SDL you might want:
* *
* SDL_LogSetAllPriority(SDL_LOG_PRIORITY_WARN); * SDL_LogSetAllPriority(SDL_LOG_PRIORITY_WARN);
* *
* Here's where the messages go on different platforms: * Here's where the messages go on different platforms:
* Windows: debug output stream *
* Android: log output * - Windows: debug output stream
* Others: standard error output (stderr) * - Android: log output
* - Others: standard error output (stderr)
*/ */
#ifndef SDL_log_h_ #ifndef SDL_log_h_

4
include/SDL_main.h
View file

@ -25,9 +25,9 @@
#include "SDL_stdinc.h" #include "SDL_stdinc.h"
/** /**
* \file SDL_main.h * # CategoryMain
* *
* Redefine main() on some platforms so that it is called by SDL. * Redefine main() on some platforms so that it is called by SDL.
*/ */
#ifndef SDL_MAIN_HANDLED #ifndef SDL_MAIN_HANDLED

5
include/SDL_metal.h
View file

@ -20,9 +20,10 @@
*/ */
/** /**
* \file SDL_metal.h * # CategoryMetal
* *
* Header file for functions to creating Metal layers and views on SDL windows. * Header file for functions to creating Metal layers and views on SDL
* windows.
*/ */
#ifndef SDL_metal_h_ #ifndef SDL_metal_h_

4
include/SDL_misc.h
View file

@ -20,9 +20,9 @@
*/ */
/** /**
* \file SDL_misc.h * # CategoryMisc
* *
* \brief Include file for SDL API functions that don't fit elsewhere. * Include file for SDL API functions that don't fit elsewhere.
*/ */
#ifndef SDL_misc_h_ #ifndef SDL_misc_h_

4
include/SDL_mouse.h
View file

@ -20,9 +20,9 @@
*/ */
/** /**
* \file SDL_mouse.h * # CategoryMouse
* *
* Include file for SDL mouse event handling. * Include file for SDL mouse event handling.
*/ */
#ifndef SDL_mouse_h_ #ifndef SDL_mouse_h_

4
include/SDL_mutex.h
View file

@ -23,9 +23,9 @@
#define SDL_mutex_h_ #define SDL_mutex_h_
/** /**
* \file SDL_mutex.h * # CategoryMutex
* *
* Functions to provide thread synchronization primitives. * Functions to provide thread synchronization primitives.
*/ */
#include "SDL_stdinc.h" #include "SDL_stdinc.h"

14
include/SDL_opengl.h
View file

@ -19,17 +19,11 @@
3. This notice may not be removed or altered from any source distribution. 3. This notice may not be removed or altered from any source distribution.
*/ */
/** /*
* \file SDL_opengl.h * This is a simple file to encapsulate the OpenGL API headers.
* *
* This is a simple file to encapsulate the OpenGL API headers. * Define NO_SDL_GLEXT if you have your own version of glext.h and want
*/ * to disable the version included in SDL_opengl.h.
/**
* \def NO_SDL_GLEXT
*
* Define this if you have your own version of glext.h and want to disable the
* version included in SDL_opengl.h.
*/ */
#ifndef SDL_opengl_h_ #ifndef SDL_opengl_h_

7
include/SDL_opengles.h
View file

@ -19,11 +19,10 @@
3. This notice may not be removed or altered from any source distribution. 3. This notice may not be removed or altered from any source distribution.
*/ */
/** /*
* \file SDL_opengles.h * This is a simple file to encapsulate the OpenGL ES 1.X API headers.
*
* This is a simple file to encapsulate the OpenGL ES 1.X API headers.
*/ */
#include "SDL_config.h" #include "SDL_config.h"
#ifdef __IPHONEOS__ #ifdef __IPHONEOS__

7
include/SDL_opengles2.h
View file

@ -19,11 +19,10 @@
3. This notice may not be removed or altered from any source distribution. 3. This notice may not be removed or altered from any source distribution.
*/ */
/** /*
* \file SDL_opengles2.h * This is a simple file to encapsulate the OpenGL ES 2.0 API headers.
*
* This is a simple file to encapsulate the OpenGL ES 2.0 API headers.
*/ */
#include "SDL_config.h" #include "SDL_config.h"
#if !defined(_MSC_VER) && !defined(SDL_USE_BUILTIN_OPENGL_DEFINITIONS) #if !defined(_MSC_VER) && !defined(SDL_USE_BUILTIN_OPENGL_DEFINITIONS)

4
include/SDL_pixels.h
View file

@ -20,9 +20,9 @@
*/ */
/** /**
* \file SDL_pixels.h * # CategoryPixels
* *
* Header for the enumerated pixel format definitions. * Header for the enumerated pixel format definitions.
*/ */
#ifndef SDL_pixels_h_ #ifndef SDL_pixels_h_

4
include/SDL_platform.h
View file

@ -20,9 +20,9 @@
*/ */
/** /**
* \file SDL_platform.h * # CategoryPlatform
* *
* Try to get a standard set of platform defines. * Try to get a standard set of platform defines.
*/ */
#ifndef SDL_platform_h_ #ifndef SDL_platform_h_

4
include/SDL_power.h
View file

@ -23,9 +23,9 @@
#define SDL_power_h_ #define SDL_power_h_
/** /**
* \file SDL_power.h * # CategoryPower
* *
* Header for the SDL power management routines. * Header for the SDL power management routines.
*/ */
#include "SDL_stdinc.h" #include "SDL_stdinc.h"

22
include/SDL_quit.h
View file

@ -20,19 +20,7 @@
*/ */
/** /**
* \file SDL_quit.h * # CategoryQuit
*
* Include file for SDL quit event handling.
*/
#ifndef SDL_quit_h_
#define SDL_quit_h_
#include "SDL_stdinc.h"
#include "SDL_error.h"
/**
* \file SDL_quit.h
* *
* An SDL_QUIT event is generated when the user tries to close the application * An SDL_QUIT event is generated when the user tries to close the application
* window. If it is ignored or filtered out, the window will remain open. * window. If it is ignored or filtered out, the window will remain open.
@ -46,10 +34,14 @@
* to determine the cause of an SDL_QUIT event, but setting a signal * to determine the cause of an SDL_QUIT event, but setting a signal
* handler in your application will override the default generation of * handler in your application will override the default generation of
* quit events for that signal. * quit events for that signal.
*
* \sa SDL_Quit()
*/ */
#ifndef SDL_quit_h_
#define SDL_quit_h_
#include "SDL_stdinc.h"
#include "SDL_error.h"
/* There are no functions directly affecting the quit event */ /* There are no functions directly affecting the quit event */
#define SDL_QuitRequested() \ #define SDL_QuitRequested() \

4
include/SDL_rect.h
View file

@ -20,9 +20,9 @@
*/ */
/** /**
* \file SDL_rect.h * # CategoryRect
* *
* Header file for SDL_rect definition and management functions. * Header file for SDL_rect definition and management functions.
*/ */
#ifndef SDL_rect_h_ #ifndef SDL_rect_h_

35
include/SDL_render.h
View file

@ -20,29 +20,30 @@
*/ */
/** /**
* \file SDL_render.h * # CategoryRender
* *
* Header file for SDL 2D rendering functions. * Header file for SDL 2D rendering functions.
* *
* This API supports the following features: * This API supports the following features:
* * single pixel points
* * single pixel lines
* * filled rectangles
* * texture images
* *
* The primitives may be drawn in opaque, blended, or additive modes. * - single pixel points
* - single pixel lines
* - filled rectangles
* - texture images
* *
* The texture images may be drawn in opaque, blended, or additive modes. * The primitives may be drawn in opaque, blended, or additive modes.
* They can have an additional color tint or alpha modulation applied to
* them, and may also be stretched with linear interpolation.
* *
* This API is designed to accelerate simple 2D operations. You may * The texture images may be drawn in opaque, blended, or additive modes. They
* want more functionality such as polygons and particle effects and * can have an additional color tint or alpha modulation applied to them, and
* in that case you should use SDL's OpenGL/Direct3D support or one * may also be stretched with linear interpolation.
* of the many good 3D engines.
* *
* These functions must be called from the main thread. * This API is designed to accelerate simple 2D operations. You may want more
* See this bug for details: https://github.com/libsdl-org/SDL/issues/986 * functionality such as polygons and particle effects and in that case you
* should use SDL's OpenGL/Direct3D support or one of the many good 3D
* engines.
*
* These functions must be called from the main thread. See this bug for
* details: https://github.com/libsdl-org/SDL/issues/986
*/ */
#ifndef SDL_render_h_ #ifndef SDL_render_h_

14
include/SDL_rwops.h
View file

@ -19,15 +19,15 @@
3. This notice may not be removed or altered from any source distribution. 3. This notice may not be removed or altered from any source distribution.
*/ */
/**
* \file SDL_rwops.h
*
* This file provides a general interface for SDL to read and write
* data streams. It can easily be extended to files, memory, etc.
*/
/* WIKI CATEGORY: RWOPS */ /* WIKI CATEGORY: RWOPS */
/**
* # CategoryRWOPS
*
* This file provides a general interface for SDL to read and write data
* streams. It can easily be extended to files, memory, etc.
*/
#ifndef SDL_rwops_h_ #ifndef SDL_rwops_h_
#define SDL_rwops_h_ #define SDL_rwops_h_

4
include/SDL_scancode.h
View file

@ -20,9 +20,9 @@
*/ */
/** /**
* \file SDL_scancode.h * # CategoryScancode
* *
* Defines keyboard scancodes. * Defines keyboard scancodes.
*/ */
#ifndef SDL_scancode_h_ #ifndef SDL_scancode_h_

5
include/SDL_sensor.h
View file

@ -20,10 +20,9 @@
*/ */
/** /**
* \file SDL_sensor.h * # CategorySensor
*
* Include file for SDL sensor event handling
* *
* Include file for SDL sensor event handling
*/ */
#ifndef SDL_sensor_h_ #ifndef SDL_sensor_h_

12
include/SDL_stdinc.h
View file

@ -19,14 +19,14 @@
3. This notice may not be removed or altered from any source distribution. 3. This notice may not be removed or altered from any source distribution.
*/ */
/**
* \file SDL_stdinc.h
*
* This is a general header that includes C language support.
*/
/* WIKI CATEGORY: StdInc */ /* WIKI CATEGORY: StdInc */
/**
* # CategoryStdInc
*
* This is a general header that includes C language support.
*/
#ifndef SDL_stdinc_h_ #ifndef SDL_stdinc_h_
#define SDL_stdinc_h_ #define SDL_stdinc_h_

4
include/SDL_surface.h
View file

@ -20,9 +20,9 @@
*/ */
/** /**
* \file SDL_surface.h * # CategorySurface
* *
* Header file for SDL_Surface definition and management functions. * Header file for SDL_Surface definition and management functions.
*/ */
#ifndef SDL_surface_h_ #ifndef SDL_surface_h_

4
include/SDL_system.h
View file

@ -20,9 +20,9 @@
*/ */
/** /**
* \file SDL_system.h * # CategorySystem
* *
* Include file for platform specific SDL API functions * Include file for platform specific SDL API functions
*/ */
#ifndef SDL_system_h_ #ifndef SDL_system_h_

24
include/SDL_syswm.h
View file

@ -19,10 +19,17 @@
3. This notice may not be removed or altered from any source distribution. 3. This notice may not be removed or altered from any source distribution.
*/ */
/** /* WIKI CATEGORY: SYSWM */
* \file SDL_syswm.h
/*
* # CategorySYSWM
* *
* Include file for SDL custom system window manager hooks. * Include file for SDL custom system window manager hooks.
*
* Your application has access to a special type of event SDL_SYSWMEVENT,
* which contains window-manager specific information and arrives whenever
* an unhandled window event occurs. This event is ignored by default, but
* you can enable it with SDL_EventState().
*/ */
#ifndef SDL_syswm_h_ #ifndef SDL_syswm_h_
@ -33,17 +40,6 @@
#include "SDL_video.h" #include "SDL_video.h"
#include "SDL_version.h" #include "SDL_version.h"
/*
* \file SDL_syswm.h
*
* Your application has access to a special type of event SDL_SYSWMEVENT,
* which contains window-manager specific information and arrives whenever
* an unhandled window event occurs. This event is ignored by default, but
* you can enable it with SDL_EventState().
*/
/* WIKI CATEGORY: SYSWM */
struct SDL_SysWMinfo; struct SDL_SysWMinfo;
#if !defined(SDL_PROTOTYPES_ONLY) #if !defined(SDL_PROTOTYPES_ONLY)

4
include/SDL_thread.h
View file

@ -23,9 +23,9 @@
#define SDL_thread_h_ #define SDL_thread_h_
/** /**
* \file SDL_thread.h * # CategoryThread
* *
* Header for the SDL thread management routines. * Header for the SDL thread management routines.
*/ */
#include "SDL_stdinc.h" #include "SDL_stdinc.h"

4
include/SDL_timer.h
View file

@ -23,9 +23,9 @@
#define SDL_timer_h_ #define SDL_timer_h_
/** /**
* \file SDL_timer.h * # CategoryTimer
* *
* Header for the SDL time management routines. * Header for the SDL time management routines.
*/ */
#include "SDL_stdinc.h" #include "SDL_stdinc.h"

4
include/SDL_touch.h
View file

@ -20,9 +20,9 @@
*/ */
/** /**
* \file SDL_touch.h * # CategoryTouch
* *
* Include file for SDL touch event handling. * Include file for SDL touch event handling.
*/ */
#ifndef SDL_touch_h_ #ifndef SDL_touch_h_

7
include/SDL_types.h
View file

@ -19,11 +19,6 @@
3. This notice may not be removed or altered from any source distribution. 3. This notice may not be removed or altered from any source distribution.
*/ */
/**
* \file SDL_types.h
*
* \deprecated
*/
/* DEPRECATED */ /* DEPRECATED */
#include "SDL_stdinc.h" #include "SDL_stdinc.h"

4
include/SDL_version.h
View file

@ -20,9 +20,9 @@
*/ */
/** /**
* \file SDL_version.h * # CategoryVersion
* *
* This header defines the current SDL version. * This header defines the current SDL version.
*/ */
#ifndef SDL_version_h_ #ifndef SDL_version_h_

4
include/SDL_video.h
View file

@ -20,9 +20,9 @@
*/ */
/** /**
* \file SDL_video.h * # CategoryVideo
* *
* Header file for SDL video functions. * Header file for SDL video functions.
*/ */
#ifndef SDL_video_h_ #ifndef SDL_video_h_

4
include/SDL_vulkan.h
View file

@ -20,9 +20,9 @@
*/ */
/** /**
* \file SDL_vulkan.h * # CategoryVulkan
* *
* Header file for functions to creating Vulkan surfaces on SDL windows. * Header file for functions to creating Vulkan surfaces on SDL windows.
*/ */
#ifndef SDL_vulkan_h_ #ifndef SDL_vulkan_h_

14
include/begin_code.h
View file

@ -19,16 +19,14 @@
3. This notice may not be removed or altered from any source distribution. 3. This notice may not be removed or altered from any source distribution.
*/ */
/**
* \file begin_code.h
*
* This file sets things up for C dynamic library function definitions,
* static inlined functions, and structures aligned at 4-byte alignment.
* If you don't like ugly C preprocessor code, don't look at this file. :)
*/
/* WIKI CATEGORY: BeginCode */ /* WIKI CATEGORY: BeginCode */
/**
* begin_code.h sets things up for C dynamic library function definitions,
* static inlined functions, and structures aligned at 4-byte alignment.
* If you don't like ugly C preprocessor code, don't look at this file. :)
*/
/* This shouldn't be nested -- included it around code only. */ /* This shouldn't be nested -- included it around code only. */
#ifdef SDL_begin_code_h #ifdef SDL_begin_code_h
#error Nested inclusion of begin_code.h #error Nested inclusion of begin_code.h