আপনার গেম কোডে টিউনিং ফর্ক লাইব্রেরি সংহত করতে এই বিষয়ের ফাংশনগুলি ব্যবহার করুন৷
include/tuningfork/tuningfork.h এর হেডার ফাইলটিতে টিউনিং ফর্ক লাইব্রেরির মূল ইন্টারফেস রয়েছে। include/tuningfork/tuningfork_extra.h এর ফাইলটিতে ইউটিলিটি ফাংশন রয়েছে।
বেশ কিছু ফাংশন প্রোটোকল বাফারের সিরিয়ালাইজেশন নেয়। আপনার গেমের মধ্যে প্রোটোকল বাফার ব্যবহার করার বিষয়ে আরও জানতে, প্রোটোকল বাফার সম্পর্কে দেখুন।
ফাংশন প্যারামিটার এবং রিটার্ন মান হেডার এবং রেফারেন্স API ডকুমেন্টেশনে ব্যাখ্যা করা হয়েছে।
অ্যান্ড্রয়েড পারফরম্যান্স টিউনার লাইফসাইকেল ফাংশন
একটি টিউনিং ফর্ক উদাহরণের জীবনচক্র নিয়ন্ত্রণ করতে নিম্নলিখিত ফাংশনগুলি ব্যবহার করুন।
আরম্ভ করুন
TFErrorCode TuningFork_init(const TFSettings* settings, JNIEnv* env, jobject context);
স্টার্ট-আপের সময় আপনাকে অবশ্যই এই ফাংশনটি একবার কল করতে হবে, সাধারণত অ্যাপের onCreate() পদ্ধতি দ্বারা নির্বাহিত নেটিভ কোডের মধ্যে থেকে। এটি টিউনিং ফর্ক লাইব্রেরির প্রয়োজনীয় ডেটা বরাদ্দ করে।
আপনার অ্যাপের মধ্যে assets/tuningfork এ আপনার একটি tuningfork_settings.bin ফাইল থাকতে হবে, যাতে হিস্টোগ্রাম এবং টীকা সেটিংস রয়েছে। পাঠ্য ফাইলটিকে বাইনারিতে রূপান্তর করতে, পাঠ্য বনাম বাইনারি উপস্থাপনা দেখুন।
আপনি settings যে ক্ষেত্রগুলি পূরণ করেন তা নির্ধারণ করে কিভাবে লাইব্রেরি নিজেই শুরু করে।
/**
* @brief Initialization settings
* Zero any values that are not being used.
*/
struct TFSettings {
/**
* Cache object to be used for upload data persistence.
* If unset, data is persisted to /data/local/tmp/tuningfork
*/
const TFCache* persistent_cache;
/**
* The address of the Swappy_injectTracers function.
* If this is unset, you need to call TuningFork_tick explicitly.
* If it is set, telemetry for 4 instrument keys is automatically recorded.
*/
SwappyTracerFn swappy_tracer_fn;
/**
* Callback
* If set, this is called with the fidelity parameters that are downloaded.
* If unset, you need to call TuningFork_getFidelityParameters explicitly.
*/
ProtoCallback fidelity_params_callback;
/**
* A serialized protobuf containing the fidelity parameters to be uploaded
* for training.
* Set this to nullptr if you are not using training mode. Note that these
* are used instead of the default parameters loaded from the APK, if they
* are present and there are neither a successful download nor saved parameters.
*/
const CProtobufSerialization* training_fidelity_params;
/**
* A null-terminated UTF-8 string containing the endpoint that Tuning Fork
* will connect to for parameter, upload, and debug requests. This overrides
* the value in base_uri in the settings proto and is intended for debugging
* purposes only.
*/
const char* endpoint_uri_override;
/**
* The version of Swappy that swappy_tracer_fn comes from.
*/
uint32_t swappy_version;
/**
* The number of each metric that is allowed to be allocated at any given
* time. If any element is zero, the default for that metric type is used.
* Memory for all metrics is allocated up-front at initialization. When all
* metrics of a given type are allocated, further requested metrics are not
* added and data is lost.
*/
TuningFork_MetricLimits max_num_metrics;
};
আপনি যদি শুরু করার সময় ফ্রেম পেসিং API থেকে Swappy_injectTracer() ফাংশন ( OpenGL , Vulkan ) পাস করেন, তাহলে টিউনিং ফর্ক লাইব্রেরি স্বয়ংক্রিয়ভাবে ফ্রেম টাইম রেকর্ড করবে আপনি স্পষ্টভাবে টিক ফাংশনগুলিকে কল না করেই৷ এটি ডেমো অ্যাপে করা হয়:
void InitTf(JNIEnv* env, jobject activity) {
SwappyGL_init(env, activity);
swappy_enabled = SwappyGL_isEnabled();
TFSettings settings {};
if (swappy_enabled) {
settings.swappy_tracer_fn = &SwappyGL_injectTracer;
settings.swappy_version = Swappy_version();
}
...
}
ধ্বংস করুন
TFErrorCode TuningFork_destroy();
আপনি শাট-ডাউন এ এই ফাংশন কল করতে পারেন. এই ফাংশনটি টিউনিং ফর্ক লাইব্রেরি দ্বারা ব্যবহৃত যেকোন মেমরি ডিলোকেটিং করার আগে পরবর্তী আপলোডের জন্য সমস্ত বর্তমানে সঞ্চিত-হিস্টোগ্রাম ডেটা জমা দেওয়ার চেষ্টা করে।
ফ্লাশ
TFErrorCode TuningFork_flush();
এই ফাংশনটি রেকর্ড করা হিস্টোগ্রামগুলিকে ফ্লাশ করে (উদাহরণস্বরূপ, যখন গেমটি ব্যাকগ্রাউন্ড বা ফোরগ্রাউন্ডে পাঠানো হয়)। এটি ডেটা ফ্লাশ করে না যদি ন্যূনতম আপলোড সময়কাল, যার একটি ডিফল্ট এক মিনিট থাকে, আগের আপলোডের পর থেকে অতিবাহিত না হয়৷
বিশ্বস্ততার পরামিতি সেট করুন
TFErrorCode TuningFork_setFidelityParameters(const CProtobufSerialization* params);
এই ফাংশনটি বর্তমান বিশ্বস্ততার পরামিতিগুলিকে ওভাররাইড করে যার সাথে ফ্রেম ডেটা যুক্ত। যখন একজন খেলোয়াড় ম্যানুয়ালি গেমের গুণমান সেটিংস পরিবর্তন করে তখন আপনার এই ফাংশনটি কল করা উচিত।
টীকা
TFErrorCode TuningFork_setCurrentAnnotation(const CProtobufSerialization* annotation);
এই ফাংশনটি পরবর্তী টিকগুলির সাথে যুক্ত করার জন্য টীকা সেট করে। এটি TFERROR_INVALID_ANNOTATION প্রদান করে যদি টীকাটি ডিকোড করার সময় কোনো ত্রুটি থাকে এবং যদি কোনো ত্রুটি না থাকে তাহলে TFERROR_OK ।
প্রতি-ফ্রেম ফাংশন
TFErrorCode TuningFork_frameTick(TFInstrumentKey key);
এই ফাংশনটি প্রদত্ত key দিয়ে পূর্ববর্তী টিক এবং key এবং বর্তমান টীকা-এর সাথে যুক্ত হিস্টোগ্রামে বর্তমান সময়ের মধ্যে সময় রেকর্ড করে।
TFErrorCode TuningFork_frameDeltaTimeNanos(TFInstrumentKey key, TFDuration dt);
এই ফাংশন key এবং বর্তমান টীকা সম্পর্কিত হিস্টোগ্রামে সময়কাল রেকর্ড করে।
TFErrorCode TuningFork_startTrace(TFInstrumentKey key, TraceHandle* handle);
এই ফাংশনটি প্রদত্ত key এর সাথে যুক্ত একটি ট্রেস হ্যান্ডেলে একটি হ্যান্ডেল সেট করে।
TFErrorCode TuningFork_endTrace(TraceHandle handle);
এই ফাংশনটি ব্যবহৃত হওয়া key এবং বর্তমান টীকাটির সাথে যুক্ত হিস্টোগ্রামে যুক্ত TuningFork_startTrace() কলের পর থেকে সময়ের ব্যবধান রেকর্ড করে।
অ্যাপের জীবনচক্র ফাংশন
typedef enum TuningFork_LifecycleState {
TUNINGFORK_STATE_UNINITIALIZED = 0,
TUNINGFORK_STATE_ONCREATE = 1,
TUNINGFORK_STATE_ONSTART = 2,
TUNINGFORK_STATE_ONSTOP = 3,
TUNINGFORK_STATE_ONDESTROY = 4,
} TuningFork_LifecycleState;
TFErrorCode TuningFork_reportLifecycleEvent(TuningForkLifecycleState state);
আপনার গেমের প্রধান কার্যকলাপে উপযুক্ত জীবনচক্র পদ্ধতি থেকে এই ফাংশনটি কল করুন, উপযুক্ত enum পাস করুন। গেমের লাইফসাইকেল ইভেন্টগুলি রেকর্ড করার মাধ্যমে, আপনার গেম কখন ক্র্যাশ হতে পারে বা ব্যবহারকারীরা কখন ছেড়ে দিচ্ছেন (উদাহরণস্বরূপ, দীর্ঘ লোডিং ইভেন্টের সময়) এপিটি আরও ভালভাবে বুঝতে সক্ষম।
উন্নত ফাংশন
নিম্নলিখিত ফাংশন tuningfork_extra.h এ উপলব্ধ।
একটি APK এ ফাইল খুঁজুন এবং লোড করুন
এই ফাংশনটি প্রদত্ত ফাইলের নামের সাথে APK-এর assets/tuningfork ডিরেক্টরি থেকে fidelityParams লোড করে। fidelityParams অবশ্যই একটি FidelityParams বার্তার একটি সিরিয়ালাইজেশন হতে হবে৷ আরও তথ্যের জন্য, গুণমানের স্তর নির্ধারণ করুন দেখুন।
সিরিয়ালাইজেশনের মালিকানা কলারের কাছে চলে যায়, যেকোন মেমরি ডিলোকেট করার জন্য তাকে অবশ্যই CProtobufSerialization_Free কল করতে হবে।
একটি পৃথক থ্রেডে বিশ্বস্ততা পরামিতি ডাউনলোড করুন
বিশ্বস্ততা প্যারামগুলি পুনরুদ্ধার করতে একটি ডাউনলোড থ্রেড সক্রিয় করে৷ প্যারামস ডাউনলোড বা একটি সময় শেষ না হওয়া পর্যন্ত থ্রেড অনুরোধটি পুনরায় চেষ্টা করে। ডাউনলোড করা প্যারামগুলি স্থানীয়ভাবে সংরক্ষণ করা হয়। অ্যাপটি পুনরায় চালু হলে, এটি ডিফল্ট প্যারামের পরিবর্তে এই ডাউনলোড করা প্যারামগুলি ব্যবহার করে।
ডিভাইসে সঞ্চিত বিশ্বস্ততা পরামিতিগুলি সংরক্ষণ করুন এবং মুছুন
এই ফাংশন শুধুমাত্র বিশেষজ্ঞ মোডে প্রয়োজন যেখানে বিশ্বস্ততা পরামিতি একটি সার্ভার থেকে ডাউনলোড করা হয়। এটি হয় সংরক্ষণ করে বা মুছে দেয় (যদি fidelity_params শূন্য হয়) স্থানীয়ভাবে সঞ্চিত ফাইলগুলি যেগুলি সার্ভারের কাছে পৌঁছানো যায় না তখন ব্যবহার করা হয়।
ওয়েব অনুরোধ
লাইব্রেরি সার্ভার এন্ডপয়েন্টে নিম্নলিখিত ধরণের অনুরোধ করে:
- শুরু করার সময় একটি
generateTuningParametersঅনুরোধ করা হয়। - গেমপ্লে চলাকালীন, সার্ভারে ডেটা পাঠানোর জন্য একটি
uploadTelemetryঅনুরোধ পর্যায়ক্রমে করা হয়। - ডিবাগ APKগুলি
debugInfoঅনুরোধগুলিও পাঠাতে পারে, যা সেটিংস, ডিফল্ট বিশ্বস্ততা পরামিতি এবংdev_tuningfork.protoকাঠামোর একটি ডিবাগ সার্ভারকে জানায়।
অফলাইন খেলোয়াড়
আরম্ভ করার সময় কোন উপলব্ধ সংযোগ না থাকলে, অনুরোধটি ক্রমবর্ধমান ব্যাক-অফ সময়ের সাথে কয়েকবার পুনরায় চেষ্টা করা হয়।
আপলোডের সময় কোন সংযোগ না থাকলে, আপলোডটি ক্যাশে করা হয়। আপনি শুরুতে একটি TFCache অবজেক্ট পাস করে আপনার নিজস্ব ক্যাশিং প্রক্রিয়া প্রদান করতে পারেন। আপনি যদি নিজের ক্যাশে প্রদান না করেন, আপলোডগুলি অস্থায়ী সঞ্চয়স্থানে ফাইল হিসাবে সংরক্ষণ করা হয়৷