1/*
2 * Copyright (c) 2008-2015, NVIDIA CORPORATION. All rights reserved.
3 *
4 * NVIDIA CORPORATION and its licensors retain all intellectual property
5 * and proprietary rights in and to this software, related documentation
6 * and any modifications thereto. Any use, reproduction, disclosure or
7 * distribution of this software and related documentation without an express
8 * license agreement from NVIDIA CORPORATION is strictly prohibited.
9 */
10
11#ifndef PX_PROFILE_ZONE_H
12#define PX_PROFILE_ZONE_H
13
14#include "physxprofilesdk/PxProfileEventBufferClientManager.h"
15#include "physxprofilesdk/PxProfileEventNames.h"
16#include "physxprofilesdk/PxProfileEventFilter.h"
17#include "physxprofilesdk/PxProfileEventSender.h"
18
19namespace physx {
20
21 class PxUserCustomProfiler;
22
23 class PxProfileZoneManager;
24 /**
25 * The profiling system was setup in the expectation that there would be several
26 * systems that each had its own island of profile information. PhysX, client code,
27 * and APEX would be the first examples of these. Each one of these islands is represented
28 * by a profile zone.
29 *
30 * A profile zone combines a name, a place where all the events coming from its interface
31 * can flushed, and a mapping from event number to full event name.
32 *
33 * It also provides a top level filtering service where profile events
34 * can be filtered by event id.
35 *
36 * The profile zone implements a system where if there is no one
37 * listening to events it doesn't provide a mechanism to send them. In this way
38 * the event system is short circuited when there aren't any clients.
39 *
40 * All functions on this interface should be considered threadsafe.
41 */
42 class PxProfileZone : public PxProfileZoneClientManager
43 , public PxProfileNameProvider
44 , public PxProfileEventSender
45 , public PxProfileEventFlusher
46 {
47 protected:
48 virtual ~PxProfileZone(){}
49 public:
50 virtual const char* getName() = 0;
51 virtual void release() = 0;
52
53 virtual void setProfileZoneManager(PxProfileZoneManager* inMgr) = 0;
54 virtual PxProfileZoneManager* getProfileZoneManager() = 0;
55
56 //Get or create a new event id for a given name.
57 //If you pass in a previously defined event name (including one returned)
58 //from the name provider) you will just get the same event id back.
59 virtual PxU16 getEventIdForName( const char* inName ) = 0;
60
61 /**
62 \brief Reserve a contiguous set of profile event ids for a set of names.
63
64 This function does not do any meaningful error checking other than to ensure
65 that if it does generate new ids they are contiguous. If the first name is already
66 registered, that is the ID that will be returned regardless of what other
67 names are registered. Thus either use this function alone (without the above
68 function) or don't use it.
69 If you register "one","two","three" and the function returns an id of 4, then
70 "one" is mapped to 4, "two" is mapped to 5, and "three" is mapped to 6.
71
72 \param inNames set of names to register.
73 \param inLen Length of the name list.
74
75 \return The first id associated with the first name. The rest of the names
76 will be associated with monotonically incrementing PxU16 values from the first
77 id.
78 */
79 virtual PxU16 getEventIdsForNames( const char** inNames, PxU32 inLen ) = 0;
80
81 /**
82 \brief Specifies an optional user custom profiler interface for this profile zone.
83 \param up Specifies the PxUserCustomProfiler interface for this zone. A NULL disables event notification.
84 */
85 virtual void setUserCustomProfiler(PxUserCustomProfiler* up) = 0;
86 /**
87 \brief Create a new profile zone.
88
89 \param inFoundation memory allocation is controlled through the foundation if one is passed in.
90 \param inSDKName Name of the profile zone; useful for clients to understand where events came from.
91 \param inProvider Mapping from event id -> event name.
92 \param inEventBufferByteSize Size of the canonical event buffer. This does not need to be a large number
93 as profile events are fairly small individually.
94 \return a profile zone implementation.
95 */
96 static PxProfileZone& createProfileZone( PxFoundation* inFoundation, const char* inSDKName, PxProfileNames inNames = PxProfileNames(), PxU32 inEventBufferByteSize = 0x4000 /*16k*/ );
97 static PxProfileZone& createProfileZone( PxAllocatorCallback* inAllocator, const char* inSDKName, PxProfileNames inNames = PxProfileNames(), PxU32 inEventBufferByteSize = 0x4000 /*16k*/ );
98
99
100 /** deprecated forms of the above functions */
101 static PxProfileZone& createProfileZone( PxFoundation* inFoundation, const char* inSDKName, PxProfileNameProvider& inProvider, PxU32 inEventBufferByteSize = 0x4000 /*16k*/ );
102 static PxProfileZone& createProfileZone( PxAllocatorCallback* inAllocator, const char* inSDKName, PxProfileNameProvider& inProvider, PxU32 inEventBufferByteSize = 0x4000 /*16k*/ );
103 };
104}
105#endif // PX_PROFILE_ZONE_H
106