cssysdef.h File Reference (Crystal Space 2.0 Public API Reference)

| ## Public API Reference

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Files

- File List
- File Members

Namespaces | Defines | Functions
cssysdef.h File Reference

This file should be #included before any other Crystal Space header files. More...

`#include "csdef.h"`
`#include "csutil/csosdefs.h"`
`#include "csextern.h"`
`#include <stdio.h>`
`#include <sys/param.h>`
`#include "csutil/threading/atomicops.h"`
`#include "csutil/threading/mutex.h"`
`#include <stdlib.h>`
`#include <malloc.h>`
`#include <new>`
`#include "csutil/nullptr.h"`

Go to the source code of this file.

## Namespaces
namespace | CS
| Main namespace for CrystalSpace.
namespace | CS::Debug
| Debugging utilities and helpers.
## Defines
#define | CS_ALIGNED_MEMBER(Member, Align) Member __attribute__((aligned(Align)))
| Macro to align a class member (or local variable) to a specific byte boundary.
#define | CS_ALIGNED_STRUCT(Kind, Align) Kind __attribute__((aligned(Align)))
| Macro to declare a struct aligned to a specific byte boundary.
#define | CS_ALLOC_STACK_ARRAY(type, var, size) type var [size]
| Dynamic stack memory allocation.
#define | CS_ALLOC_STACK_ARRAY_FALLBACK(Type, Name, Size, Thresshold)
| Dynamic stack memory allocation.
#define | CS_ASSERT(x) (void)0
| Assertion.
#define | CS_ASSERT_MSG(m, x) (void)0
| Same as CS_ASSERT(expr), but additionally prints msg to `stderr`.
#define | CS_DEBUG_BREAK
| Stops program execution and break into debugger, if present - otherwise, probably just throws an exception/signal (ie crashes).
#define | CS_DEPRECATED_METHOD CS_ATTRIBUTE_DEPRECATED
| Use the CS_DEPRECATED_METHOD macro in front of method declarations to indicate that they are deprecated.
#define | CS_DEPRECATED_METHOD
| Use the CS_DEPRECATED_METHOD macro in front of method declarations to indicate that they are deprecated.
#define | CS_DEPRECATED_METHOD_MSG(msg) CS_ATTRIBUTE_DEPRECATED_MSG(msg)
| A variant of CS_DEPRECATED_METHOD that also emits the message msg on compilers that support it.
#define | CS_DEPRECATED_METHOD_MSG(msg) CS_DEPRECATED_METHOD
| A variant of CS_DEPRECATED_METHOD that also emits the message msg on compilers that support it.
#define | CS_DEPRECATED_TYPE CS_ATTRIBUTE_DEPRECATED
| Use the CS_DEPRECATED_TYPE macro after type declarations to indicate that they are deprecated.
#define | CS_DEPRECATED_TYPE
| Use the CS_DEPRECATED_TYPE macro after type declarations to indicate that they are deprecated.
#define | CS_DEPRECATED_TYPE_MSG(msg) CS_ATTRIBUTE_DEPRECATED_MSG(msg)
| A variant of CS_DEPRECATED_TYPE that also emits the message msg on compilers that support it.
#define | CS_DEPRECATED_TYPE_MSG(msg) CS_DEPRECATED_TYPE
| A variant of CS_DEPRECATED_TYPE that also emits the message msg on compilers that support it.
#define | CS_DEPRECATED_VAR(decl) decl CS_ATTRIBUTE_DEPRECATED
| Use the CS_DEPRECATED_VAR macro tol indicate that a variable or class/struct is deprecated.
#define | CS_DEPRECATED_VAR(decl) decl
| Use the CS_DEPRECATED_VAR macro tol indicate that a variable or class/struct is deprecated.
#define | CS_DEPRECATED_VAR_MSG(msg, decl) decl CS_ATTRIBUTE_DEPRECATED_MSG(msg)
| A variant of CS_DEPRECATED_VAR that also emits the message msg on compilers that support it.
#define | CS_DEPRECATED_VAR_MSG(msg, decl) CS_DEPRECATED_VAR(decl)
| A variant of CS_DEPRECATED_VAR that also emits the message msg on compilers that support it.
#define | CS_DEPRECATION_WARNINGS_DISABLE
| Disable deprecation warnings in following statements.
#define | CS_DEPRECATION_WARNINGS_ENABLE
| Enable deprecation warnings in following statements.
#define | CS_FUNCTION_NAME __PRETTY_FUNCTION__
| Macro that resolves to a compiler-specific variable or string that contains the name of the current function.
#define | CS_HEADER_GLOBAL(X, Y) CS_HEADER_GLOBAL_COMPOSE(X,Y)
| The CS_HEADER_GLOBAL() macro composes a pathname from two components and wraps the path in `<' and `>'.
#define | CS_HEADER_LOCAL(X, Y) CS_HEADER_LOCAL_COMPOSE1(X,Y)
| The CS_HEADER_LOCAL() macro composes a pathname from two components and wraps the path in double-quotes.
#define | CS_IMPLEMENT_IMPLICIT_PTR_CAST(classname)
| Implements a static member function for a class which can be used to perform implicit pointer casts.
#define | CS_IMPLICIT_PTR_CAST(classname, ptr) (classname::_CS_IMPLICITPTRCAST_NAME(ptr))
| Perform a compiler implicit cast of a pointer to another pointer type using a static member function declared with the `CS_IMPLEMENT_IMPLICIT_PTR_CAST` macro.
#define | CS_NO_EXCEPTIONS
| This is defined when the project was compiled without support for exceptions.
#define | CS_STRING_TO_WIDE(x) CS_STRING_TO_WIDE_(x)
| Convert a string to a wide string.
#define | CS_VA_COPY(dest, src) __va_copy(dest, src)
| Copies the state of a va_list value.
Plugin namespace helpers
To avoid symbol conflicts when employing static linking, it is a good idea to put everything into a private namespace. The CS_PLUGIN_NAMESPACE_BEGIN and CS_PLUGIN_NAMESPACE_END macros help with that by putting the plugin namespace into a sub-namespace for plugins. Use like:
     #include <...>

     CS_IMPLEMENT_PLUGIN

     CS_PLUGIN_NAMESPACE_BEGIN(MyPlugin)
     {
       ...
       MyClass::MyClass (...) { ... }
       ...
     }
     CS_PLUGIN_NAMESPACE_END(MyPlugin)
To refer to members of the namespace (e.g. for template specializations, use CS_PLUGIN_NAMESPACE_NAME.
#define | CS_PLUGIN_NAMESPACE_BEGIN(name) namespace CS_NAMESPACE_PACKAGE_NAME { namespace Plugin { namespace name
#define | CS_PLUGIN_NAMESPACE_END(name) } }
#define | CS_PLUGIN_NAMESPACE_NAME(name) CS_NAMESPACE_PACKAGE_NAME::Plugin::name
## Functions
static void | CS::Debug::DebugBreak ()
| Break execution for debugging purposes.
void | CS::Debug::DumpAllocateMemoryBlocks ()
| Print all memory blocks allocated with the "checking" functions, including where they were allocated, to a file "allocations.txt".
bool | CS::Debug::VerifyAllMemory ()
| Verify that all memory blocks allocated with the "checking" functions did not overrun or the allocated space.
ptmalloc memory allocation
void * | ptmalloc (size_t n)
void | ptfree (void *p)
void * | ptrealloc (void *p, size_t n)
void * | ptcalloc (size_t n, size_t s)
'Cookie' memory allocation
void * | ptmalloc_sentinel (size_t n)
void | ptfree_sentinel (void *p)
void * | ptrealloc_sentinel (void *p, size_t n)
void * | ptcalloc_sentinel (size_t n, size_t s)
'Located' memory allocation
void * | ptmalloc_located (size_t n)
void | ptfree_located (void *p)
void * | ptrealloc_located (void *p, size_t n)
void * | ptcalloc_located (size_t n, size_t s)
'Checking' memory allocation
Located allocation, but additionally all allocated blocks are frequently checked for corruption, not just when a block is freed.
void * | ptmalloc_checking (size_t n)
void | ptfree_checking (void *p)
void * | ptrealloc_checking (void *p, size_t n)
void * | ptcalloc_checking (size_t n, size_t s)
Default Crystal Space memory allocation
Always the same memory allocation functions as internally used by Crystal Space.
void * | cs_malloc (size_t n)
void | cs_free (void *p)
void * | cs_realloc (void *p, size_t n)
void * | cs_calloc (size_t n, size_t s)

## Detailed Description

This file should be #included before any other Crystal Space header files.

It sets up a compilation environment which smooths over differences between platforms, allowing the same code to compile cleanly over a variety of operating systems and build tools. It also provides a number of utility macros useful to projects utilizing Crystal Space and to the Crystal Space code itself.

Definition in file cssysdef.h.

## Define Documentation

#define CS_ALIGNED_MEMBER | ( |  | Member,
|  |  | Align
| ) |  | Member __attribute__((aligned(Align)))

Macro to align a class member (or local variable) to a specific byte boundary.

Example:

     struct MyStruct
     {
       CS_ALIGNED_MEMBER(int x[4], 16);
     };

Definition at line 1127 of file cssysdef.h.

#define CS_ALIGNED_STRUCT | ( |  | Kind,
|  |  | Align
| ) |  | Kind __attribute__((aligned(Align)))

Macro to declare a struct aligned to a specific byte boundary.

Example:

     CS_STRUCT_ALIGN(struct, 16) MyStruct
     {
       int x;
     };

Definition at line 1140 of file cssysdef.h.

#define CS_ALLOC_STACK_ARRAY | ( |  | type,
|  |  | var,
|  |  | size
| ) |  | type var [size]

Dynamic stack memory allocation.

Parameters:

  type | Type of the array elements.
  var | Name of the array to be allocated.
  size | Number of elements to be allocated.

Definition at line 307 of file cssysdef.h.

#define CS_ALLOC_STACK_ARRAY_FALLBACK | ( |  | Type,
|  |  | Name,
|  |  | Size,
|  |  | Thresshold
| ) |  |

Value:

    Type* Name = ((Size) > (Thresshold)) ? \
            (Type*)cs_malloc((Size)*sizeof(Type)) : \
            (Type*)alloca((Size)*sizeof(Type)); \
      CS::StackArrayHelper<Type> Name##Del (Name, ((Size) > (Thresshold)));

Dynamic stack memory allocation.

This version fallbacks to normal allocation in case the number of items on the stack would be too high.

Parameters:

  type | Type of the array elements.
  var | Name of the array to be allocated.
  size | Number of elements to be allocated.
  Thresshold | is the maximum number of items before switching to normal allocation.

Definition at line 894 of file cssysdef.h.

#define CS_ASSERT | ( |  | x | ) | (void)0

Assertion.

If expr is false, a message containing the failing expression as well as a call stack is printed to `stderr` and a debug break is performed

Remarks:
  Breaking execution can be avoided at runtime by setting the environment variable `"CS_ASSERT_IGNORE"` to a value other than 0.

#define CS_ASSERT_MSG | ( |  | m,
|  |  | x
| ) |  | (void)0

Same as CS_ASSERT(expr), but additionally prints msg to `stderr`.

#define CS_DEBUG_BREAK

Stops program execution and break into debugger, if present - otherwise, probably just throws an exception/signal (ie crashes).

#define CS_DEPRECATED_METHOD CS_ATTRIBUTE_DEPRECATED

Use the CS_DEPRECATED_METHOD macro in front of method declarations to indicate that they are deprecated.

Example:

     struct iFoo : iBase {
       CS_DEPRECATED_METHOD virtual void Plankton() const = 0;
     }

Compilers which are capable of flagging deprecation will exhibit a warning when it encounters client code invoking methods so tagged.

Definition at line 195 of file cssysdef.h.

#define CS_DEPRECATED_METHOD

Use the CS_DEPRECATED_METHOD macro in front of method declarations to indicate that they are deprecated.

Example:

     struct iFoo : iBase {
       CS_DEPRECATED_METHOD virtual void Plankton() const = 0;
     }

Compilers which are capable of flagging deprecation will exhibit a warning when it encounters client code invoking methods so tagged.

Definition at line 195 of file cssysdef.h.

#define CS_DEPRECATED_METHOD_MSG | ( |  | msg | ) | CS_ATTRIBUTE_DEPRECATED_MSG(msg)

A variant of CS_DEPRECATED_METHOD that also emits the message msg on compilers that support it.

Definition at line 207 of file cssysdef.h.

#define CS_DEPRECATED_METHOD_MSG | ( |  | msg | ) | CS_DEPRECATED_METHOD

A variant of CS_DEPRECATED_METHOD that also emits the message msg on compilers that support it.

Definition at line 207 of file cssysdef.h.

#define CS_DEPRECATED_TYPE CS_ATTRIBUTE_DEPRECATED

Use the CS_DEPRECATED_TYPE macro after type declarations to indicate that they are deprecated.

Example:

     typedef CS_DEPRECATED_TYPE csFoo csBar;
     class CS_DEPRECATED_TYPE csBaz { };

Compilers which are capable of flagging deprecation will exhibit a warning when it encounters client code using types so tagged.

Definition at line 225 of file cssysdef.h.

#define CS_DEPRECATED_TYPE

Use the CS_DEPRECATED_TYPE macro after type declarations to indicate that they are deprecated.

Example:

     typedef CS_DEPRECATED_TYPE csFoo csBar;
     class CS_DEPRECATED_TYPE csBaz { };

Compilers which are capable of flagging deprecation will exhibit a warning when it encounters client code using types so tagged.

Definition at line 225 of file cssysdef.h.

#define CS_DEPRECATED_TYPE_MSG | ( |  | msg | ) | CS_ATTRIBUTE_DEPRECATED_MSG(msg)

A variant of CS_DEPRECATED_TYPE that also emits the message msg on compilers that support it.

Definition at line 237 of file cssysdef.h.

#define CS_DEPRECATED_TYPE_MSG | ( |  | msg | ) | CS_DEPRECATED_TYPE

A variant of CS_DEPRECATED_TYPE that also emits the message msg on compilers that support it.

Definition at line 237 of file cssysdef.h.

#define CS_DEPRECATED_VAR | ( |  | decl | ) | decl CS_ATTRIBUTE_DEPRECATED

Use the CS_DEPRECATED_VAR macro tol indicate that a variable or class/struct is deprecated.

Example:

     struct MyStuff
     {
       int newStuff;
       CS_DEPRECATED_VAR(int oldStuff);
     };

Compilers which are capable of flagging deprecation will exhibit a warning when it encounters client code using types so tagged.

Definition at line 258 of file cssysdef.h.

#define CS_DEPRECATED_VAR | ( |  | decl | ) | decl

Use the CS_DEPRECATED_VAR macro tol indicate that a variable or class/struct is deprecated.

Example:

     struct MyStuff
     {
       int newStuff;
       CS_DEPRECATED_VAR(int oldStuff);
     };

Compilers which are capable of flagging deprecation will exhibit a warning when it encounters client code using types so tagged.

Definition at line 258 of file cssysdef.h.

#define CS_DEPRECATED_VAR_MSG | ( |  | msg,
|  |  | decl
| ) |  | decl CS_ATTRIBUTE_DEPRECATED_MSG(msg)

A variant of CS_DEPRECATED_VAR that also emits the message msg on compilers that support it.

Definition at line 270 of file cssysdef.h.

#define CS_DEPRECATED_VAR_MSG | ( |  | msg,
|  |  | decl
| ) |  | CS_DEPRECATED_VAR(decl)

A variant of CS_DEPRECATED_VAR that also emits the message msg on compilers that support it.

Definition at line 270 of file cssysdef.h.

#define CS_DEPRECATION_WARNINGS_DISABLE

Disable deprecation warnings in following statements.

Always try to actually fix the root cause of a deprecation warning before employing this. Should be followed by CS_DEPRECATION_WARNINGS_ENABLE after the statements that caused the warnings. Suitable for use in macros.

Definition at line 1268 of file cssysdef.h.

#define CS_DEPRECATION_WARNINGS_ENABLE

Enable deprecation warnings in following statements.

Suitable for use in macros.

Definition at line 1269 of file cssysdef.h.

#define CS_FUNCTION_NAME __PRETTY_FUNCTION__

Macro that resolves to a compiler-specific variable or string that contains the name of the current function.

Definition at line 782 of file cssysdef.h.

#define CS_HEADER_GLOBAL | ( |  | X,
|  |  | Y
| ) |  | CS_HEADER_GLOBAL_COMPOSE(X,Y)

The CS_HEADER_GLOBAL() macro composes a pathname from two components and wraps the path in `<' and `>'.

This macro is useful in cases where one does not have the option of augmenting the preprocessor's header search path, even though the include path for some header file may vary from platform to platform. For instance, on many platforms OpenGL headers are in a `GL' directory, whereas on other platforms they are in an `OpenGL' directory. As an example, in the first case, the platform might define the preprocessor macro GLPATH with the value `GL', and in the second case GLPATH would be given the value `OpenGL'. To actually include an OpenGL header, such as gl.h, the following code would be used:

     #include CS_HEADER_GLOBAL(GLPATH,gl.h)

Definition at line 342 of file cssysdef.h.

#define CS_HEADER_LOCAL | ( |  | X,
|  |  | Y
| ) |  | CS_HEADER_LOCAL_COMPOSE1(X,Y)

The CS_HEADER_LOCAL() macro composes a pathname from two components and wraps the path in double-quotes.

This macro is useful in cases where one does not have the option of augmenting the preprocessor's header search path, even though the include path for some header file may vary from platform to platform. For example, assuming that the preprocessor macro UTILPATH is defined with some platform-specific value, to actually include a header, such as util.h, the following code would be used:

     #include CS_HEADER_LOCAL(UTILPATH,util.h)

Definition at line 357 of file cssysdef.h.

#define CS_IMPLEMENT_IMPLICIT_PTR_CAST | ( |  | classname | ) |

Value:

    inline static classname* _CS_IMPLICITPTRCAST_NAME (classname* ptr) \
      { \
        return ptr;\
      }

Implements a static member function for a class which can be used to perform implicit pointer casts.

Parameters:

  classname | Name of the class that the macro is being used in.

Remarks:
  This macro is intended to support typecasting within macros, allowing the compiler to provide a more descriptive error message. Use CS_IMPLEMENT_IMPLICIT_PTR_CAST() in the declaration of the class and CS_IMPLICIT_PTR_CAST() in the macro declaration.

Example:

       struct iObjectRegistry : public iBase
       {
         // Allow implicit casts through static function.
         CS_IMPLEMENT_IMPLICIT_PTR_CAST(iObjectRegistry);
         ...
       }

       #define CS_QUERY_REGISTRY_TAG(Reg, Tag) \
        csPtr<iBase> (CS_IMPLICIT_PTR_CAST(iObjectRegistry, Reg)->Get (Tag))

Definition at line 1174 of file cssysdef.h.

#define CS_IMPLICIT_PTR_CAST | ( |  | classname,
|  |  | ptr
| ) |  | (classname::_CS_IMPLICITPTRCAST_NAME(ptr))

Perform a compiler implicit cast of a pointer to another pointer type using a static member function declared with the `CS_IMPLEMENT_IMPLICIT_PTR_CAST` macro.

Parameters:

  classname | Name of the class to convert to
  ptr | Pointer to be convereted into

See also:
  CS_IMPLEMENT_IMPLICIT_PTR_CAST

Definition at line 1188 of file cssysdef.h.

#define CS_NO_EXCEPTIONS

This is defined when the project was compiled without support for exceptions.

Definition at line 284 of file cssysdef.h.

#define CS_STRING_TO_WIDE | ( |  | x | ) | CS_STRING_TO_WIDE_(x)

Convert a string to a wide string.

Also works in macros.

     void bar (const wchar_t* baz);
     #define FOO(x) bar (CS_STRING_TO_WIDE (#x));

Definition at line 1212 of file cssysdef.h.

#define CS_VA_COPY | ( |  | dest,
|  |  | src
| ) |  | __va_copy(dest, src)

Copies the state of a va_list value.

Definition at line 1198 of file cssysdef.h.