CoreMiscDefines.h File Reference

#include "HAL/Platform.h"
#include "HAL/PreprocessorHelpers.h"

Go to the source code of this file.

Classes
struct	FDeprecationCompileError
struct	TStaticDeprecateExpression< bIsDeprecated >
struct	FPlatformUserId
struct	FInputDeviceId
struct	FPlatformInputDeviceState

Macros
#define	WARNING_LOCATION(Line)   __FILE__ "(" PREPROCESSOR_TO_STRING(Line) ")"
#define	PLAYWORLD_PACKAGE_PREFIX   TEXT("UEDPIE")
#define	WITH_EDITORONLY_DATA   0
#define	WITH_METADATA   WITH_EDITORONLY_DATA
#define	UE_CHECK_DISABLE_OPTIMIZATION   0
#define	UE_DISABLE_OPTIMIZATION_SHIP   PRAGMA_DISABLE_OPTIMIZATION_ACTUAL
#define	UE_ENABLE_OPTIMIZATION_SHIP   PRAGMA_ENABLE_OPTIMIZATION_ACTUAL
#define	UE_DISABLE_OPTIMIZATION   UE_DISABLE_OPTIMIZATION_SHIP
#define	UE_ENABLE_OPTIMIZATION   UE_ENABLE_OPTIMIZATION_SHIP
#define	PRAGMA_DISABLE_OPTIMIZATION
#define	PRAGMA_ENABLE_OPTIMIZATION
#define	FORCEINLINE_DEBUGGABLE   FORCEINLINE
#define	UE_DONT_INLINE_CALL
#define	CLOCK_CYCLES(Timer)
#define	UNCLOCK_CYCLES(Timer)
#define	SHUTDOWN_IF_EXIT_REQUESTED
#define	RETURN_IF_EXIT_REQUESTED
#define	RETURN_VAL_IF_EXIT_REQUESTED(x)
#define	PURE_VIRTUAL(func, ...)   { LowLevelFatalError(TEXT("Pure virtual not implemented (%s)"), TEXT(#func)); __VA_ARGS__ }
#define	USING_CODE_ANALYSIS   0
#define	CA_IN
#define	CA_OUT
#define	CA_READ_ONLY
#define	CA_WRITE_ONLY
#define	CA_VALID_POINTER
#define	CA_CHECK_RETVAL
#define	CA_NO_RETURN
#define	CA_SUPPRESS(WarningNumber)
#define	CA_ASSUME(Expr)   ((void)sizeof((bool)(Expr)))
#define	CA_CONSTANT_IF(Condition)   if (Condition)
#define	USING_INSTRUMENTATION   0
#define	USING_THREAD_SANITISER   0
#define	TSAN_SAFE
#define	TSAN_BEFORE(Addr)
#define	TSAN_AFTER(Addr)
#define	TSAN_ATOMIC(Type)   Type
#define	UE_PUSH_MACRO(name)   __pragma(push_macro(name))
#define	UE_POP_MACRO(name)   __pragma(pop_macro(name))
#define	ANONYMOUS_VARIABLE(Name)   PREPROCESSOR_JOIN(Name, __LINE__)
#define	UE_CALL_ONCE(Func, ...)   static int32 ANONYMOUS_VARIABLE(ThreadSafeOnce) = ((Func)(__VA_ARGS__), 1)
#define	UE_DEPRECATED(Version, Message)   [[deprecated(Message " - Please update your code to the new API before upgrading to the next release, otherwise your project will no longer compile.")]]
#define	UE_DEPRECATED_ERROR(Version, Message)   [[deprecated(Message " - ** This is a compile error so as to avoid data loss, or similar. ** You will need to update your code to get it to compile correctly.")]]
#define	UE_DEPRECATED_ERROR_WITH_MOVED_MEMBER_MESSAGE(Version, Member, Message)
#define	UE_DEPRECATED_ERROR_WITH_MOVED_MEMBER(Version, Member)   UE_DEPRECATED_ERROR_WITH_MOVED_MEMBER_MESSAGE(Version, Member, "The member " #Member " has moved. Use the Get/Set" #Member " accessors instead.")
#define	UE_DEPRECATED_ERROR_WITH_MOVED_BOOL_MEMBER(Version, Member)   UE_DEPRECATED_ERROR_WITH_MOVED_MEMBER_MESSAGE(Version, b##Member, "The member b" #Member " has moved. Use the Get/Set" #Member " accessors instead.")
#define	UE_INTERNAL
#define	PRAGMA_DISABLE_INTERNAL_WARNINGS
#define	PRAGMA_ENABLE_INTERNAL_WARNINGS
#define	UE_EXPERIMENTAL(Version, Message)
#define	PRAGMA_DISABLE_EXPERIMENTAL_WARNINGS
#define	PRAGMA_ENABLE_EXPERIMENTAL_WARNINGS
#define	UE_DEPRECATED_FORGAME   PREPROCESSOR_NOTHING_FUNCTION
#define	UE_DEPRECATED_FORENGINE   UE_DEPRECATED
#define	UE_DEPRECATED_HEADER(Version, Message)   _Pragma(PREPROCESSOR_TO_STRING(message(Message " Please update your code to the new API before upgrading to the next release, otherwise your project will no longer compile.")))
#define	UE_STRIP_DEPRECATED_PROPERTIES   0
#define	UE_STATIC_DEPRECATE(Version, bExpression, Message)
#define	UE_STATIC_ASSERT_WARN(bExpression, Message)
#define	UE_PTRDIFF_TO_INT32(argument)   static_cast<int32>(argument)
#define	UE_PTRDIFF_TO_UINT32(argument)   static_cast<uint32>(argument)
#define	UE_NONCOPYABLE(TypeName)
#define	UE_WITH_REMOTE_OBJECT_HANDLE   0

Enumerations
enum	{ INDEX_NONE = -1 }
enum	{ UNICODE_BOM = 0xfeff }
enum	EForceInit { ForceInit , ForceInitToZero }
enum	ENoInit { NoInit }
enum	EConstEval { ConstEval }
enum	EInPlace { InPlace }
enum	EPerElement { PerElement }
enum class	EInputDeviceConnectionState : uint8 { Invalid , Unknown , Disconnected , Connected }

Variables
constexpr FPlatformUserId	PLATFORMUSERID_NONE
constexpr FInputDeviceId	INPUTDEVICEID_NONE

Macro Definition Documentation

ANONYMOUS_VARIABLE

#define ANONYMOUS_VARIABLE

(

Name

)

PREPROCESSOR_JOIN(Name, __LINE__)

CA_ASSUME

#define CA_ASSUME

(

Expr

)

((void)sizeof((bool)(Expr)))

CA_CHECK_RETVAL

#define CA_CHECK_RETVAL

CA_CONSTANT_IF

#define CA_CONSTANT_IF

(

Condition

)

if (Condition)

CA_IN

#define CA_IN

CA_NO_RETURN

#define CA_NO_RETURN

CA_OUT

#define CA_OUT

CA_READ_ONLY

#define CA_READ_ONLY

CA_SUPPRESS

#define CA_SUPPRESS

(

WarningNumber

)

CA_VALID_POINTER

#define CA_VALID_POINTER

CA_WRITE_ONLY

#define CA_WRITE_ONLY

CLOCK_CYCLES

#define CLOCK_CYCLES

(

Timer

)

FORCEINLINE_DEBUGGABLE

#define FORCEINLINE_DEBUGGABLE   FORCEINLINE

PLAYWORLD_PACKAGE_PREFIX

#define PLAYWORLD_PACKAGE_PREFIX   TEXT("UEDPIE")

PRAGMA_DISABLE_EXPERIMENTAL_WARNINGS

#define PRAGMA_DISABLE_EXPERIMENTAL_WARNINGS

PRAGMA_DISABLE_INTERNAL_WARNINGS

#define PRAGMA_DISABLE_INTERNAL_WARNINGS

PRAGMA_DISABLE_OPTIMIZATION

#define PRAGMA_DISABLE_OPTIMIZATION

Value:

    UE_DEPRECATED_MACRO(5.2, "PRAGMA_DISABLE_OPTIMIZATION has been deprecated. Use UE_DISABLE_OPTIMIZATION for temporary development or UE_DISABLE_OPTIMIZATION_SHIP to submit") \
    UE_DISABLE_OPTIMIZATION_SHIP

PRAGMA_ENABLE_EXPERIMENTAL_WARNINGS

#define PRAGMA_ENABLE_EXPERIMENTAL_WARNINGS

PRAGMA_ENABLE_INTERNAL_WARNINGS

#define PRAGMA_ENABLE_INTERNAL_WARNINGS

PRAGMA_ENABLE_OPTIMIZATION

#define PRAGMA_ENABLE_OPTIMIZATION

Value:

    UE_DEPRECATED_MACRO(5.2, "PRAGMA_ENABLE_OPTIMIZATION has been deprecated. Use UE_ENABLE_OPTIMIZATION for temporary development or UE_ENABLE_OPTIMIZATION_SHIP to submit") \
    UE_ENABLE_OPTIMIZATION_SHIP

PURE_VIRTUAL

#define PURE_VIRTUAL	(		func,
			...
	)		{ LowLevelFatalError(TEXT("Pure virtual not implemented (%s)"), TEXT(#func)); __VA_ARGS__ }

RETURN_IF_EXIT_REQUESTED

#define RETURN_IF_EXIT_REQUESTED

RETURN_VAL_IF_EXIT_REQUESTED

#define RETURN_VAL_IF_EXIT_REQUESTED

(

x

)

SHUTDOWN_IF_EXIT_REQUESTED

#define SHUTDOWN_IF_EXIT_REQUESTED

TSAN_AFTER

#define TSAN_AFTER

(

Addr

)

TSAN_ATOMIC

#define TSAN_ATOMIC

(

Type

)

Type

TSAN_BEFORE

#define TSAN_BEFORE

(

Addr

)

TSAN_SAFE

#define TSAN_SAFE

UE_CALL_ONCE

#define UE_CALL_ONCE	(		Func,
			...
	)		static int32 ANONYMOUS_VARIABLE(ThreadSafeOnce) = ((Func)(__VA_ARGS__), 1)

Thread-safe call once helper for void functions, similar to std::call_once without the std::once_flag

UE_CHECK_DISABLE_OPTIMIZATION

#define UE_CHECK_DISABLE_OPTIMIZATION   0

UE_DEPRECATED

#define UE_DEPRECATED	(		Version,
			Message
	)		[[deprecated(Message " - Please update your code to the new API before upgrading to the next release, otherwise your project will no longer compile.")]]

Macro for marking up deprecated code, functions and types.

This should be used as syntactic replacement for the [[deprecated]] attribute which provides a UE version number like the old DEPRECATED macro.

Features that are marked as deprecated are scheduled to be removed from the code base in a future release. If you are using a deprecated feature in your code, you should replace it before upgrading to the next release. See the Upgrade Notes in the release notes for the release in which the feature was marked deprecated.

Sample usage (note the slightly different syntax for classes and structures):

UE_DEPRECATED(5.xx, "MyFunction has been deprecated, please use MyNewFunction instead.")
void MyFunction();

UE_DEPRECATED(5.xx, "FMyType has been deprecated, please use MyNewType instead.")
typedef FThing FMyType;

using FMyAlias UE_DEPRECATED(5.xx, "FMyAlias has been deprecated, please use MyNewAlias instead.") = FThing;

UE_DEPRECATED(5.xx, "MyVariable has been deprecated and serves no purpose anymore")
int32 MyVariable;

namespace UE_DEPRECATED(5.xx, "MyNamespace has been renamed MyNewNamespace, please use this instead.") MyNamespace
{
}

Unfortunately, clang will complain that [the] "declaration of [an] anonymous class must
be a definition" for API types.  To work around this, first forward declare the type as
deprecated, then declare the type with the visibility macro.  Note that macros like
USTRUCT must immediately precede the the type declaration, not the forward declaration.

struct UE_DEPRECATED(5.xx, "FMyStruct has been deprecated and shall not be used anymore.") FMyStruct;
USTRUCT()
struct MODULE_API FMyStruct
{
};

class UE_DEPRECATED(5.xx, "FMyClass has been deprecated and shall not be used anymore.") FMyClass;
class MODULE_API FMyClass
{
};

enum class UE_DEPRECATED(5.xx, "EMyEnumeration has been deprecated, use EMyEnumeration instead.") EMyEnumeration
{
    Zero = 0,
    One UE_DEPRECATED(5.xx, "EMyEnumeration::One is not a valid enum entry anymore, please use another one.") = 1,
    Two = 2
};

Unfortunately, VC++ will complain about using member functions and fields from deprecated
class/structs even for class/struct implementation e.g.:
class UE_DEPRECATED(5.xx, "DeprecatedClass has been deprecated and shall not be used anymore.") DeprecatedClass
{
public:
    DeprecatedClass() {}

    float GetMyFloat()
    {
        return MyFloat; // This line will cause warning that deprecated field is used.
    }
private:
    float MyFloat;
};

To get rid of this warning, place all code not called in class implementation in non-deprecated
base class and deprecate only derived one. This may force you to change some access specifiers
from private to protected, e.g.:

class DeprecatedClass_Base_DEPRECATED
{
protected: // MyFloat is protected now, so DeprecatedClass has access to it.
    float MyFloat;
};

class UE_DEPRECATED(5.xx, "DeprecatedClass has been deprecated and shall not be used anymore.") DeprecatedClass : DeprecatedClass_Base_DEPRECATED
{
public:
    DeprecatedClass() {}

    float GetMyFloat()
    {
        return MyFloat;
    }
};

template <typename T>
class UE_DEPRECATED(5.xx, "DeprecatedClassTemplate has been deprecated and shall not be used anymore.") DeprecatedClassTemplate
{
};

template <typename T>
UE_DEPRECATED(5.xx, "DeprecatedFunctionTemplate has been deprecated and shall not be used anymore.")
void DeprecatedFunctionTemplate()
{
}

Parameters

Version	The release number in which the feature was marked deprecated. Note: 'all', as in UE_DEPRECATED(all, ...), can be used for reflected code which has to stick around forever and is marked with meta-data like DeprecatedFunction or DeprecatedProperty. It indicates that the deprecation grace period is now over but that this property/function will remain deprecated for all time.
Message	A message containing upgrade notes.

UE_DEPRECATED_ERROR

#define UE_DEPRECATED_ERROR	(		Version,
			Message
	)		[[deprecated(Message " - ** This is a compile error so as to avoid data loss, or similar. ** You will need to update your code to get it to compile correctly.")]]

UE_DEPRECATED_ERROR_WITH_MOVED_BOOL_MEMBER

#define UE_DEPRECATED_ERROR_WITH_MOVED_BOOL_MEMBER	(		Version,
			Member
	)		UE_DEPRECATED_ERROR_WITH_MOVED_MEMBER_MESSAGE(Version, b##Member, "The member b" #Member " has moved. Use the Get/Set" #Member " accessors instead.")

This version prints out a message for the accessor without the b(SetFoo, not SetbFoo), but as such you need to pass in the bool Member without the b

UE_DEPRECATED_ERROR_WITH_MOVED_MEMBER

#define UE_DEPRECATED_ERROR_WITH_MOVED_MEMBER	(		Version,
			Member
	)		UE_DEPRECATED_ERROR_WITH_MOVED_MEMBER_MESSAGE(Version, Member, "The member " #Member " has moved. Use the Get/Set" #Member " accessors instead.")

A version of the above that prints out a premade message with member name

UE_DEPRECATED_ERROR_WITH_MOVED_MEMBER_MESSAGE

#define UE_DEPRECATED_ERROR_WITH_MOVED_MEMBER_MESSAGE	(		Version,
			Member,
			Message
	)

Value:

        [[deprecated(Message " ** This is a compile error so as to avoid data loss, or similar. ** You will need to update your code to get it to compile correctly.")]] \
        FDeprecationCompileError Member;

A version of the above that declares a compilation-error type with a message indicating it has moved and you need to use accessor functions instead.

UE_DEPRECATED_FORENGINE

#define UE_DEPRECATED_FORENGINE   UE_DEPRECATED

UE_DEPRECATED_FORGAME

#define UE_DEPRECATED_FORGAME   PREPROCESSOR_NOTHING_FUNCTION

UE_DEPRECATED_HEADER

#define UE_DEPRECATED_HEADER	(		Version,
			Message
	)		_Pragma(PREPROCESSOR_TO_STRING(message(Message " Please update your code to the new API before upgrading to the next release, otherwise your project will no longer compile.")))

Macro which can be placed in a header to throw a deprecation warning when it is included.

UE_DISABLE_OPTIMIZATION

#define UE_DISABLE_OPTIMIZATION   UE_DISABLE_OPTIMIZATION_SHIP

UE_DISABLE_OPTIMIZATION_SHIP

#define UE_DISABLE_OPTIMIZATION_SHIP   PRAGMA_DISABLE_OPTIMIZATION_ACTUAL

UE_DONT_INLINE_CALL

#define UE_DONT_INLINE_CALL

UE_ENABLE_OPTIMIZATION

#define UE_ENABLE_OPTIMIZATION   UE_ENABLE_OPTIMIZATION_SHIP

UE_ENABLE_OPTIMIZATION_SHIP

#define UE_ENABLE_OPTIMIZATION_SHIP   PRAGMA_ENABLE_OPTIMIZATION_ACTUAL

UE_EXPERIMENTAL

#define UE_EXPERIMENTAL	(		Version,
			Message
	)

Macro for marking up experimental code, functions and types from non-experimental modules. This informs the users that there is no guarantee that the API won't change or be removed in future releases and that they should use at their own risk. Using an API marked as such in a non-engine module will trigger a compilation warning (this relies on the c++ [[deprecated]] attribute internally) that can be suppressed by either :

• Using PRAGMA_DISABLE_EXPERIMENTAL_WARNINGS and PRAGMA_ENABLE_EXPERIMENTAL_WARNINGS around the call site (preferred method)
• Setting bValidateExperimentalApi to false in the calling module's build rules, thus telling the entire module that any experimental API call is accepted
• Setting bTreatAsEngineModule to true in the calling module's build rules, thus telling the entire module that any experimental (OR internal) API call is accepted

Please refer to UE_DEPRECATED for how to use the macro.

Parameters

Version	The release number in which the feature was introduced. This does not give an indication for how long this API will exist as "experimental". It is only there to inform the users about when the experimental API was first introduced. After some time, this API may be removed or it may become official, at which point it will stop being marked as UE_EXPERIMENTAL.
Message	A message that may contain additional details about the usage of this experimental API.

UE_INTERNAL

#define UE_INTERNAL

Macro for marking up engine-internal code, functions and types. This informs the users that there is no guarantee that the API won't change or be removed in future releases and that they should use at their risk. Using an API marked as such in a non-engine module will trigger a compilation warning (this relies on the c++ [[deprecated]] attribute internally) that can be suppressed by either :

• Using PRAGMA_DISABLE_INTERNAL_WARNINGS and PRAGMA_ENABLE_INTERNAL_WARNINGS around the call site (preferred method)
• Setting bValidateInternalApi to false in the calling module's build rules, thus telling the entire module that any internal API call is accepted
• Setting bTreatAsEngineModule to true in the calling module's build rules, thus telling the entire module that any internal (OR experimental) API call is accepted

It is advised to simply avoid using APIs marked as such in non-engine modules.

Please refer to UE_DEPRECATED for how to use the macro.

UE_NONCOPYABLE

#define UE_NONCOPYABLE

(

TypeName

)

Value:

    TypeName(TypeName&&) = delete; \
	TypeName(const TypeName&) = delete; \
    TypeName& operator=(const TypeName&) = delete; \
    TypeName& operator=(TypeName&&) = delete;

Makes a type non-copyable and non-movable by deleting copy/move constructors and assignment/move operators. The macro should be placed in the public section of the type for better compiler diagnostic messages. Example usage:

class FMyClassName { public: UE_NONCOPYABLE(FMyClassName) FMyClassName() = default; };

UE_POP_MACRO

#define UE_POP_MACRO

(

name

)

__pragma(pop_macro(name))

UE_PTRDIFF_TO_INT32

#define UE_PTRDIFF_TO_INT32

(

argument

)

static_cast<int32>(argument)

UE_PTRDIFF_TO_UINT32

#define UE_PTRDIFF_TO_UINT32

(

argument

)

static_cast<uint32>(argument)

UE_PUSH_MACRO

#define UE_PUSH_MACRO

(

name

)

__pragma(push_macro(name))

UE_STATIC_ASSERT_WARN

#define UE_STATIC_ASSERT_WARN	(		bExpression,
			Message
	)

Value:

    struct PREPROCESSOR_JOIN(FStaticWarningMsg_, __LINE__) { \
        [[deprecated(Message)]] \
        static constexpr int condition(TStaticDeprecateExpression<true>) { return 1; } \
        static constexpr int condition(TStaticDeprecateExpression<false>) { return 1; } \
    }; \
    enum class PREPROCESSOR_JOIN(EStaticWarningMsg_, __LINE__) { Value = PREPROCESSOR_JOIN(FStaticWarningMsg_, __LINE__)::condition(TStaticDeprecateExpression<!(bExpression)>()) }

Can be used in the same contexts as static_assert but gives a warning rather than an error

UE_STATIC_DEPRECATE

#define UE_STATIC_DEPRECATE	(		Version,
			bExpression,
			Message
	)

Value:

    struct PREPROCESSOR_JOIN(FDeprecationMsg_, __LINE__) { \
        [[deprecated(Message " - Please update your code to the new API before upgrading to the next release, otherwise your project will no longer compile.")]] \
        static constexpr int condition(TStaticDeprecateExpression<true>) { return 1; } \
        static constexpr int condition(TStaticDeprecateExpression<false>) { return 1; } \
    }; \
    enum class PREPROCESSOR_JOIN(EDeprecationMsg_, __LINE__) { Value = PREPROCESSOR_JOIN(FDeprecationMsg_, __LINE__)::condition(TStaticDeprecateExpression<!!(bExpression)>()) }

Can be used in the same contexts as static_assert but gives a warning rather than an error, and 'fails' if the expression is true rather than false.

UE_STRIP_DEPRECATED_PROPERTIES

#define UE_STRIP_DEPRECATED_PROPERTIES   0

UE_WITH_REMOTE_OBJECT_HANDLE

#define UE_WITH_REMOTE_OBJECT_HANDLE   0

Remote objects support

UNCLOCK_CYCLES

#define UNCLOCK_CYCLES

(

Timer

)

USING_CODE_ANALYSIS

#define USING_CODE_ANALYSIS   0

USING_INSTRUMENTATION

#define USING_INSTRUMENTATION   0

USING_THREAD_SANITISER

#define USING_THREAD_SANITISER   0

WARNING_LOCATION

#define WARNING_LOCATION

(

Line

)

__FILE__ "(" PREPROCESSOR_TO_STRING(Line) ")"

WITH_EDITORONLY_DATA

#define WITH_EDITORONLY_DATA   0

WITH_METADATA

#define WITH_METADATA   WITH_EDITORONLY_DATA

This controls if metadata for compiled in classes is unpacked and setup at boot time. Meta data is not normally used except by the editor.

Enumeration Type Documentation

anonymous enum

anonymous enum

Enumerator
INDEX_NONE

anonymous enum

anonymous enum

Enumerator
UNICODE_BOM

EConstEval

enum EConstEval

Enumerator
ConstEval

EForceInit

enum EForceInit

Enumerator
ForceInit
ForceInitToZero

EInPlace

enum EInPlace

Enumerator
InPlace

EInputDeviceConnectionState

enum class EInputDeviceConnectionState : uint8

strong

Represents the connection status of a given FInputDeviceId

Enumerator
Invalid	This is not a valid input device
Unknown	It is not known if this device is connected or not
Disconnected	Device is definitely connected
Connected	Definitely connected and powered on

ENoInit

enum ENoInit

Enumerator
NoInit

EPerElement

enum EPerElement

Enumerator
PerElement

Variable Documentation

INPUTDEVICEID_NONE

constexpr FInputDeviceId INPUTDEVICEID_NONE

inlineconstexpr

Static invalid input device.

PLATFORMUSERID_NONE

constexpr FPlatformUserId PLATFORMUSERID_NONE

inlineconstexpr

Static invalid platform user