red

The basic function template is also used for macros that have pages in the wiki. For simplicity, the following guidelines for functions will also apply to macros unless a specific difference is noted.

If the page describes a macro rather than a function

Action: Use the alternate description (Use this macro to...) and, if necessary, replace the word function with the word macro where appropriate throughout the page.

Note: In some rare cases it has been deemed appropriate to refer to a macro as a function in the wiki. (eg: SDL_QuitRequested()) This is not accidental. Please do not "correct" these instances. If you feel strongly that a change should be made please contact us.

Example: SDL_VERSION()

If another API page is referenced in the description

Action: Be sure to hyperlink it and use () outside the link markup if it is a function.

Example: [[SDL_FunctionName]](), [[SDL_StructureName]], SDL_GetThreadName()

If a parameter on that page is referenced in the description

Action: Use bold for the parameter name.

Note: This is a very rare occurrence.

Note: If the reference is to the parameter as a concept (ie: the window to do something with) rather than directly to the parameter itself (ie: SDL_Function(window)) do not make it bold.
Please don't just make the word bold every time it occurs on the page.

If a function refers to a callback function

Action: See the special section on callback functions below.

Note: Callback functions do not get their own pages.

Example: SDL_AddEventWatch(), SDL_AddTimer()

If the only parameter is void

Action: Delete the entire Function Parameters section, including the header.

Example: SDL_AllocRW()

Content-dependent formatting: General

If more than one statement must be included in the description

Action: Separate them with a semi-colon (;)

Note: This should be avoided whenever possible. See "If a more detailed description is required to adequately explain a parameter" below for more details.

Example: SDL_PixelFormatEnumToMasks()

If a more detailed description is required to adequately explain a parameter

Action 1 : Append the following, verbatim, to the end of the brief description
; see [[#Remarks|Remarks]] for details.

Action 2: Place the more detailed information in the Remarks section.

Action 3: See "If the Remarks section is large" below for more details.

Example: SDL_CreateWindow()

If the Remarks section is large

Action 1: Create an anchor immediately before the additional comments you are adding to the Remarks section.

Markup: Use <<Anchor(anchorname)>>, where anchorname is a name of your choosing, to create the anchor in the Remarks section. See Anchors for details.

Action 2: Modify the Remarks link in the parameter description (see Action 1 in "If a more detailed description is required to adequately explain a parameter" above) to the following:
; see [[#anchorname|Remarks]] for details
where anchorname matches the name you chose for the anchor in Action 1.

If there is a pointer associated with the parameter

Action: Avoid mentioning pointers unless they are critical to understanding the parameter or there is little other way to describe it (ie: void*)

Example: SDL_SetColorKey()

If a pointer points to something that is filled in by the function or that has been filled in

Action: Use the phrase filled in with in the description

Example: SDL_QueryTexturePixels()

If the description mentions a structure that has a page

Action 1: Use the following pattern to describe the parameter:
the/an [[SDL_StructureName]] structure to <action> or representing <some piece of information>

Action 2: Check the table below for structure-specific phrasing.

Note: Be sure to hyperlink the structure name as shown in Action 1 in the type and description columns (as appropriate) except if the row is greyed out (see If the parameter is for internal use, deprecated, or private for details).

Example: SDL_UnionRect()

If the description mentions a structure that does not have a page

Action: Use the plain English term to describe the structure (ie: SDL_Window == the window) and omit the hyperlink.

Note: Please check the current wiki before selecting this option for wording, as a page may have been created since this was written or since you last checked.

Example: SDL_RenderClear()

If the description mentions an enumeration

Action: It is not necessary to specifically describe it as an enumeration as above for structures, but DO hyperlink if it has a page except if the row is greyed out (see If the parameter is for internal use, deprecated, or private for details).

Example: SDL_PixelFormat

If a description must refer to any other page in the API

Action: Create a hyperlink to the page except if the row is greyed out (see If the parameter is for internal use, deprecated, or private for details).

If the parameter is for internal use, deprecated, or private

Action 1: Make the text in the row grey by including the following, verbatim, in the first cell of the row between the starting table markup and the text:
<rowstyle="color: #808080;">

Action 2: Include the reason (ie: internal use, etc.) in parentheses at the end of the description.

Action 3: DO NOT hyperlink any related API pages (ie: structure type) on greyed out parameters.

Example: ||<rowstyle="color: #808080;">'''param'''||description (reason)||, SDL_PixelFormat

Note: Although a rare case, any other table style markup should be included within the same set of angle brackets (<>) and separated from this markup by a space.

If a function refers to a callback function

Action: See the special section on callback functions below.

Note: Callback functions do not get their own pages.

Example: SDL_AddEventWatch(), SDL_AddTimer()

If a parameter references another parameter on that same page

Action: Use bold for the parameter name.

Note: This is a very rare occurrence.

Note: If the reference is to the parameter as a concept (ie: the window to do something with) rather than directly to the parameter itself (ie: SDL_Function(window)) do not make it bold.
Please don't just make the word bold every time it occurs on the page.

Example: SDL_EnclosePoints()

If a description is referring to something that could be any one of a group of similar items (ie: rectangles)

Action: Begin the description with a/an

Example: SDL_HasIntersection()

Note: We realize that this is a somewhat arbitrary distinction depending upon your perspective. If you are unsure whether to use a/an or the it may be helpful to do a quick text search for other pages with the same or similar parameter and copy the format there. Ultimately, though, it's not worth losing sleep over. Just pick one.

If a description is referring to a specific item from a group (ie: a specific window)

Action: Begin the description with the

Example: SDL_BlitScaled()

Note: We realize that this is a somewhat arbitrary distinction depending upon your perspective. If you are unsure whether to use a/an or the it may be helpful to do a quick text search for other pages with the same or similar parameter and copy the format there. Ultimately, though, it's not worth losing sleep over. Just pick one.

Content-dependent formatting: Specific

If the parameter is SDL_Palette* palette

Action 1: Most often this description begins with the [[SDL_Palette]] structure to, followed by what to do with the palette (ie: free, modify, etc.).

Action 2: The most common version is the [[SDL_Palette]] structure to use

Example: SDL_SetSurfacePalette(), SDL_FreePalette()

Note: Of course other phrases to describe this parameter may become necessary. A text search for "SDL_Palette* palette" should provide you with other descriptions if they arise.

If the parameter is SDL_Rect* rect(s)

Action 1 - rect: Most often this description begins with the/an [[SDL_Rect]] structure representing the rectangle to, followed by what the rectangle is for (ie: fill, draw, intersect, etc).

Action 2 - rects: When the parameter is plural it refers to an array of rectangles and will most often begin with an array of [[SDL_Rect]] structures representing the rectangles to, followed by what the rectangles are for.

Example: SDL_FillRect(), SDL_RenderDrawRect(), SDL_IntersectRectAndLine(), SDL_RenderDrawRects()

Note: Of course there are some other phrases to describe these parameters. A text search for "SDL_Rect* rect" should provide you with plenty of other examples of both the singular and plural parameters.

If the parameter is SDL_Renderer* renderer

Action: A rare exception (at least so far), this description is always the rendering context.

red

Please use the rendering context for all occurrences of this parameter unless/until it appears in the API in a different context that calls for another description. A text search for "SDL_Renderer* renderer" should be used to determine if this has become the case.

Example: SDL_RenderPresent(), SDL_RenderDrawLine(), SDL_CreateTexture()

If the parameter is SDL_Surface* surface

Action 1: Most often this description begins with the [[SDL_Surface]] structure to, followed by what is happening with the structure (ie: optimize, be locked, etc.).

Action 2: The most common versions are the [[SDL_Surface]] structure to update (often used with Set functions) or the [[SDL_Surface]] structure to query (often used with Get functions).

Action 3: Some will be best described by the following instead: the [[SDL_Surface]] structure representing <something>.

Example: SDL_SetSurfaceRLE(), SDL_LockSurface(), SDL_GetClipRect(), SDL_SaveBMP_RW()

Note: Of course there are some other phrases to describe this parameter. A text search for "SDL_Surface* surface" should provide you with plenty of other examples.

If the parameter is SDL_Texture* texture

Action 1: Most often this description begins with the texture to, followed by what is being done (ie: create, destroy, etc.).

Action 2: The most common versions are the texture to update (often used with Set functions) or the texture to query (often used with Get functions).

Example: SDL_SetTextureAlphaMod(), SDL_QueryTexturePixels(), SDL_UnlockTexture()

Note: Of course there are some other phrases to describe this parameter. A text search for "SDL_Texture* texture" should provide you with plenty of other examples.

If the parameter is SDL_Window* window

Action 1: Most often this description begins with the window to, followed by what is being done (ie: minimize, maximize, show, etc).

Action 2: The most common versions are the window to change (often used with Set functions) or the window to query (often used with Get functions).

Example: SDL_RestoreWindow(), SDL_SetWindowTitle(), SDL_GetWindowFlags()

Note: Of course there are some other phrases to describe this parameter. A text search for "SDL_Window* window" should provide you with plenty of examples.

If the parameters include fmt and ...

Action: For fmt use a printf() style message format string
For ... use additional parameters matching % tokens in the '''fmt''' string, if any.

Note: To date this is the only context for the ... parameter. If your case does not follow this pattern exactly it may be necessary to make some adjustments. Please keep them as minimal as possible while creating an accurate wiki entry.

Example: SDL_SetError(), SDL_Log()

If the return value is void

Note: This is not the same as void*! See the table below for void* return values.

Action: Delete the entire Return Value section, including the header.

Example: SDL_FreeSurface()

Replacements by type

If the return value is an int (0 or <0)

Action: Use Returns 0 on success or a negative error code on failure; call [[SDL_GetError]]() for more information.

If the return value is an int other than above or a float

Action: Replace <something> and <something else> with the applicable numbers.

Example: Returns 1 on success or 0 on failure; call [[SDL_GetError]]() for more information.

If the return value is SDL_bool

Action: Use Returns SDL_TRUE on success or SDL_FALSE on failure; call [[SDL_GetError]]() for more information.

If the return value is a pointer or NULL

Action:Replace <something> with an appropriate description of the pointer (usually leaving out any mention of the pointer, as in parameters) and replace <something else> with NULL.

Note: See "If the return value type is a structure" below for more details.

Example: SDL_HapticOpen(), SDL_GetRenderer()

If the return value type is a structure

Action: The general format will approximate: Returns an/the [[SDL_StructureName]] representing <what it represents>, for success. The failure statement will depend upon what is returned on failure, if anything. See other Ifs for options.

Note: Ideally in this case, you would search for other functions using the same return value and replicate the phrasing of others as appropriate. (Example search: "returnValue SDL_", where returnValue is replaced with the value you are interested in.)

Example: SDL_CreateRGBSurfaceFrom()

If the return value is void*

Action:See "If the return value is a pointer or NULL" above.

Note: In most cases it will be appropriate to mention the pointer for void*. Ideally, look at other similar functions for guidance.

Example: SDL_LoadFunction(), SDL_SetWindowData()

If the return value type is a Uint

Action: Replace <something> with a brief, appropriate description of the Uint.

Example: SDL_MapRGBA(), SDL_WasInit()

Note: Very rarely the Uint that is returned is a mask of enumerated values. See SDL_MasksToPixelFormatEnum() for an example of how to handle this.

If the return value type is a char or const char

Action: Replace <something> with a brief, appropriate description of the returned string.

Example: SDL_GetCurrentVideoDriver()

If there are more than 2 possible return values

Action: Add any additional values following the applicable rules above. Keep the primary success and primary failure values first and last, respectively, or place them in some other logical order (such as numerical).

Example: SDL_HapticOpened(), SDL_OpenAudio()

If the function does not have a failure state

Note: It is very rare for a function to be unable to fail. This option covers those rare cases only.

Action 1: If the function only has 1 return value state:
Omit the second part of the statement and omit the call to SDL_GetError().

Action 2: If the function has 2 return values but they don't represent success and failure:
Use Returns <something> <in this case> or <something else> otherwise.
and omit the call to SDL_GetError().

Example: only 1 return state SDL_GetAudioDeviceStatus(); alternate return state SDL_QuitRequested()

Replacements by other criteria

If a parameter on that page is referenced in the return value

Action: Use bold for the parameter name.

Note: This is a very rare occurrence.

Note: If the reference is to the parameter as a concept (ie: the window) rather than directly to the parameter itself (ie: window) do not make it bold.
Please don't just make the word bold every time it occurs on the page.

Example: SDL_LoadWAV_RW(), SDL_GL_CreateContext()

If the return value mentions a structure that has a page

Action: Use the following pattern to describe the return value:
Returns the/an [[SDL_StructureName]] structure representing <some piece of information>

Note: Be sure to hyperlink the structure name as shown.

Example: SDL_UnionRect()

If the return value mentions a structure that does not have a page

Action: Use the plain English term to describe the structure (ie: SDL_Window == window).

Note: These structures may eventually have pages or other references worth linking to, in which case please follow the instructions above for linking to items with pages of their own.

If the return value must refer to any other page in the API

Action: Create a hyperlink to the page.

If the page is for an enumeration it is not necessary to describe it as an enumeration as above for structures.

If there is more than one function in the list

Action: List the functions in alphabetical order.

If there are no related functions

Action: This section may be removed entirely (including the heading) and added back at a later time if it becomes relevant.

Header File Containing the Function*

Corresponding Category Name

SDL.h

CategoryInit

SDL_assert.h

CategoryAssertions

SDL_atomic.h

CategoryAtomic

SDL_audio.h

CategoryAudio

SDL_clipboard.h

CategoryClipboard

SDL_bits.h

CategoryBits

SDL_cpuinfo.h

CategoryCPU

SDL_endian.h

CategoryEndian

SDL_error.h

CategoryError

SDL_events.h

CategoryEvents

SDL_gamecontroller.h

CategoryGameController

SDL_haptic.h

CategoryForceFeedback

SDL_hints.h

CategoryHints

SDL_joystick.h

CategoryJoystick

SDL_keyboard.h

CategoryKeyboard

SDL_keycode.h

CategoryKeyboard

SDL_loadso.h

CategorySharedObject

SDL_log.h

CategoryLog

SDL_mouse.h

CategoryMouse

SDL_mutex.h

CategoryMutex

SDL_pixels.h

CategoryPixels

SDL_platform.h

CategoryPlatform

SDL_power.h

CategoryPower

SDL_quit.h

CategoryEvents

SDL_rect.h

CategoryRect

SDL_render.h

CategoryRender

SDL_rwops.h

CategoryIO

SDL_scancode.h

CategoryKeyboard

SDL_surface.h

CategorySurface

SDL_syswm.h

CategorySWM

SDL_thread.h

CategoryThread

SDL_timer.h

CategoryTimer

SDL_version.h

CategoryVersion

SDL_video.h

CategoryVideo

*Some exceptions exist. See above.

Function Parameters Section Formatting Details

For the parameter that refers to the callback function

Action: Use the following wording, modified as necessary, to describe the parameter:
the function to call <when/why>; see [[#Remarks|Remarks]] for details
where the text in <> is replaced with an appropriate description of when or why the callback would be called.

Note: This parameter is often named callback but may have other names (such as filter, fn, or handler).

Example: SDL_LogSetOutputFunction(), SDL_AddEventWatch(), SDL_CreateThread(), SDL_SetAssertionHandler()

For the parameter that passes user data to the callback

Action: Use the following wording, modified as necessary, to describe the parameter:
a pointer that is passed to '''callback'''
where callback is replaced with the callback function parameter name (if necessary).

Note: In rare cases, often 'Get' functions, this is a pointer to a pointer and should be described as such.

Note: This parameter is often named userdata, but may have other names (such as data or param). It is important to distinguish this parameter from other parameters that are passed to the callback also, but that are not strictly carrying "user data" (such as interval) and from other parameters that are unrelated to the callback function (such as name). See below for details.

Example: SDL_LogSetOutputFunction(), SDL_CreateThread(), SDL_AddTimer(), SDL_LogGetOutputFunction()

For other parameters related to the callback

Action: There may be other parameters that are passed to the callback function but which are sufficiently different from the user data concept that the wording above does not really apply. In these cases use a description that is appropriate. Often it will still be appropriate to include the phrase passed to '''callback''' in these descriptions.

Example: SDL_AddTimer()

For additional function parameters not related to the callback

Action: Follow any applicable guidelines listed above

Example: SDL_CreateThread()

Remarks Section Formatting Details

Location

Action: Generally the Remarks section is roughly organized in the same order as the function parameters. Callback details should be located accordingly, or at the top of the Remarks section if there isn't much else, but below any fundamental or critical remarks about the main function as a whole, if present. But, logic should prevail in determining where to place this information if the Remarks section is large. The callback information should be prominent.

Example: SDL_CreateThread(), SDL_AddEventWatch(), SDL_SetAssertionHandler()

Alignment

Action: As shown in the basic format above, only the first line should be left-justified. Everything else related directly to the callback should be indented one level (or more) to indicate it's relationship to the callback as opposed to the main function.

If the callback parameter is not callback

Action: Replace callback in the basic format above with the function parameter name used in the main function to refer to the callback function.

Example: SDL_SetEventFilter(), SDL_CreateThread(), SDL_SetAssertionHandler()

For "callback syntax" in the basic format above

Action: Replace "callback syntax" with the callback function's syntax formatted the same as the main function's syntax. (See Syntax above for details.)

If the callback function name requires any explanation

Action: Replace "where its parameters are:" in the basic format above with the following:
where <CallbackName> is <some explanation> and its parameters are:
replacing <Callbackname> with the name of the callback function and <some explanation> with an explanation of the name (ie: your function name).

Example: SDL_AddEventWatch()

For | callback parameter | description | in the basic format above

Action 1: Duplicate the line from above for each parameter in the callback (ie: there should be 2 lines for 2 parameters).

Action 2: Replace "callback parameter" with the name of each callback function parameter using the same formatting instructions as the main function except use `monospace` (surrounding backticks) rather than bold to highlight the parameter names in the first column.

Action 3: Replace "description" with an appropriate description of the callback's parameter. See the following for specific parameters.

Example: SDL_FilterEvents(), SDL_LogSetOutputFunction()

For the userdata parameter (or comparable)

Action: Use the following text (modified as necessary):
what was passed as '''userdata''' to [[SDL_MainFunctionName]]()
replacing userdata with the appropriate parameter name if necessary, and replacing MainFunctionName with the name of the primary function on the page.

Example: SDL_AddEventWatch(), SDL_AddTimer()

If the callback function's return value is important

Action 1: Replace "optional return value info..." in the basic format above with the relevant return value information. Be sure to indent text one level as shown.

Note: Callback return value information may be omitted if it is not important.

Example: SDL_AddEventWatch(), SDL_AddTimer()

If there are "optional remarks or details"

Action: Replace "optional remarks or details..." in the basic format above with any other relevant information about the callback function. Be sure to indent text at least one level as shown.

Example: SDL_LogGetOutputFunction(), SDL_LogSetOutputFunction()