ใช้ฟังก์ชันต่อไปนี้เพื่อเพิ่มการรองรับเกมคอนโทรลเลอร์ลงในเกมโดยใช้ไลบรารีเกมคอนโทรลเลอร์
เริ่มต้นและทำลายไลบรารีเกมคอนโทรลเลอร์
ใช้ฟังก์ชัน Paddleboat_init เพื่อเริ่มต้นไลบรารีเกมคอนโทรลเลอร์
Paddleboat_ErrorCode Paddleboat_init(JNIEnv *env, jobject jcontext)
Paddleboat_init ใช้พารามิเตอร์ 2 รายการดังนี้
- ตัวชี้ไปยัง
JNIEnvที่แนบมากับชุดข้อความปัจจุบัน - การอ้างอิงออบเจ็กต์ JNI
jobjectไปยังคลาสที่ได้มาจากContextออบเจ็กต์คลาสที่ได้มาContextใดๆ ก็ตามจะถูกต้อง ซึ่งรวมถึงแต่ไม่จำกัดเพียงActivity,NativeActivityหรือGameActivity
Paddleboat_init จะแสดงผล
PADDLEBOAT_NO_ERROR หากการเริ่มต้นสำเร็จ ไม่เช่นนั้นระบบจะแสดงรหัสข้อผิดพลาดที่เหมาะสม
คุณสามารถใช้ Paddleboat_isInitialized เพื่อตรวจสอบว่าไลบรารี Game Controller เริ่มต้นเรียบร้อยแล้วหรือไม่ โดยจะแสดงผลเป็นค่าบูลีน หากเป็นจริง แสดงว่า API พร้อมใช้งาน
bool Paddleboat_isInitialized()
ก่อนสิ้นสุดแอปพลิเคชัน ให้ใช้ฟังก์ชัน Paddleboat_destroy เพื่อปิดไลบรารีเกมคอนโทรลเลอร์ ฟังก์ชันนี้ใช้พารามิเตอร์เดียว ซึ่งเป็นตัวชี้ไปยัง JNIEnv ที่แนบมากับชุดข้อความปัจจุบัน
คุณจะเรียกใช้ Paddleboat_init ได้อีกครั้งหลังวันที่ Paddleboat_destroy
void Paddleboat_destroy(JNIEnv *env)
แจ้งไลบรารีเกี่ยวกับเหตุการณ์ในวงจร
ไลบรารีเกมคอนโทรลเลอร์ต้องได้รับแจ้งเกี่ยวกับเหตุการณ์วงจรกิจกรรม onStop และ onStart
เรียกใช้ฟังก์ชัน Paddleboat_onStop และ Paddleboat_onStart จากโค้ดการจัดการเหตุการณ์หยุดและเริ่ม ทั้ง 2 ฟังก์ชันใช้พารามิเตอร์เดียว ซึ่งก็คือตัวชี้ไปยัง JNIEnv ที่แนบกับชุดข้อความปัจจุบัน
void Paddleboat_onStop(JNIEnv *env)
void Paddleboat_onStart(JNIEnv *env)
ลงทะเบียนหรือนำ Callback สถานะของตัวควบคุมออก
ไลบรารี Game Controller จะใช้ Callback สถานะของคอนโทรลเลอร์เพื่อแจ้งเตือนเกมเมื่อมีการเชื่อมต่อหรือยกเลิกการเชื่อมต่อคอนโทรลเลอร์ โดยรองรับ Callback สถานะตัวควบคุมได้ครั้งละ 1 รายการเท่านั้น
- หากต้องการลงทะเบียน Callback สถานะตัวควบคุมหรือแทนที่ Callback ที่ลงทะเบียนไว้ก่อนหน้านี้ด้วยฟังก์ชัน Callback ใหม่ ให้เรียกใช้ฟังก์ชัน
Paddleboat_setControllerStatusCallback - หากต้องการนำ Callback ที่ลงทะเบียนไว้ในปัจจุบันออก ให้ส่ง
NULLหรือnullptr - พารามิเตอร์
userDataเป็นตัวชี้ที่ไม่บังคับไปยังข้อมูลที่ผู้ใช้กำหนด ระบบจะส่งพารามิเตอร์userDataไปยังฟังก์ชัน Callback ตัวชี้จะเก็บไว้ภายในจนกว่าจะมีการเปลี่ยนแปลงโดยการเรียกPaddleboat_setControllerStatusCallbackในภายหลัง
void Paddleboat_setControllerStatusCallback(Paddleboat_ControllerStatusCallback
statusCallback, void *userData)
ลายเซ็นของฟังก์ชัน Callback คือ
typedef void (*Paddleboat_ControllerStatusCallback)(
const int32_t controllerIndex,
const Paddleboat_ControllerStatus controllerStatus,
void *userData)
| พารามิเตอร์ | คำอธิบาย |
|---|---|
controllerIndex
|
ดัชนีของตัวควบคุมที่เริ่มการเรียกกลับ จะเป็นค่าระหว่าง 0 ถึง PADDLEBOAT_MAX_CONTROLLERS - 1 |
controllerStatus
|
ค่า enum เป็น
PADDLEBOAT_CONTROLLER_JUST_CONNECTED หรือ PADDLEBOAT_CONTROLLER_JUST_DISCONNECTED |
userData
|
ตัวชี้ที่ไม่บังคับ (อาจเป็น NULL) ไปยังข้อมูลที่ผู้ใช้กำหนดซึ่งระบุโดยการเรียกใช้ Paddleboat_setControllerStatusCallback ครั้งล่าสุด |
เรียกใช้ฟังก์ชันอัปเดตไลบรารีเกมคอนโทรลเลอร์
ควรเรียกใช้ฟังก์ชันอัปเดตไลบรารีเกมคอนโทรลเลอร์ Paddleboat_update 1 ครั้งต่อเฟรมเกม โดยควรเรียกใช้ใกล้กับจุดเริ่มต้นของเฟรม
ฟังก์ชันนี้ใช้พารามิเตอร์เดียว ซึ่งเป็นตัวชี้ไปยัง JNIEnv ที่แนบมากับชุดข้อความปัจจุบัน
void Paddleboat_update(JNIEnv *env)
เหตุการณ์ในกระบวนการ
เมื่อได้รับเหตุการณ์การป้อนข้อมูล เกมของคุณจะต้องส่งต่อเหตุการณ์เหล่านั้นไปยังไลบรารีเกมคอนโทรลเลอร์เพื่อตรวจสอบ ไลบรารี Game Controller จะประเมินว่าเหตุการณ์การป้อนข้อมูลเชื่อมโยงกับอุปกรณ์ที่มีการจัดการรายการใดรายการหนึ่งหรือไม่ ระบบจะประมวลผลและใช้เหตุการณ์จากอุปกรณ์ที่มีการจัดการ
ไลบรารีเกมคอนโทรลเลอร์รองรับเหตุการณ์อินพุต 2 ประเภท ได้แก่ เหตุการณ์อินพุต AInputEvents และ GameActivity
การประมวลผล AInputEvent
เกมของคุณควรส่งต่อ AInputEvents โดยการเรียกใช้
Paddleboat_processInputEvent
จากโค้ดการจัดการเหตุการณ์
int32_t Paddleboat_processInputEvent(const AInputEvent *event)
Paddleboat_processInputEvent จะแสดงผล 0 หากระบบละเว้นเหตุการณ์ และ 1 หากระบบประมวลผลและใช้เหตุการณ์โดยไลบรารีเกมคอนโทรลเลอร์
การประมวลผลเหตุการณ์ GameActivity
หากเกมของคุณใช้ GameActivity ให้ส่งต่อเหตุการณ์ GameActivityKeyEvent และ GameActivityMotionEvent โดยเรียกใช้ Paddleboat_processGameActivityKeyInputEvent หรือ Paddleboat_processGameActivityMotionInputEvent จากโค้ดการจัดการเหตุการณ์
int32_t Paddleboat_processGameActivityKeyInputEvent(const void *event,
const size_t eventSize)
int32_t Paddleboat_processGameActivityMotionInputEvent(const void *event,
const size_t eventSize)
| พารามิเตอร์ | คำอธิบาย |
|---|---|
event
|
ตัวชี้ไปยังโครงสร้าง GameActivityKeyEvent หรือ GameActivityMotionEvent ขึ้นอยู่กับฟังก์ชันที่เรียกใช้ |
eventSize
|
ขนาดเป็นไบต์ของโครงสร้างเหตุการณ์ที่ส่งในพารามิเตอร์ event |
ทั้ง 2 ฟังก์ชันจะแสดงผล 0 หากระบบละเว้นเหตุการณ์ และ 1 หากระบบประมวลผลและใช้เหตุการณ์โดยไลบรารีเกมคอนโทรลเลอร์
GameActivity ต้องระบุแกนการเคลื่อนไหวที่ใช้งานอยู่โดยใช้ฟังก์ชัน GameActivityPointerAxes_enableAxis การเรียกใช้
Paddleboat_getActiveAxisMask
จะแสดงผลบิตมาสก์ของแกนการเคลื่อนไหวที่ใช้งานอยู่ในปัจจุบันซึ่งใช้โดยตัวควบคุมที่เชื่อมต่ออยู่
uint64_t Paddleboat_getActiveAxisMask()
ดูตัวอย่างวิธีจัดการปัญหานี้ได้ที่ตัวอย่างไลบรารีเกมคอนโทรลเลอร์ที่ใช้ GameActivity ตัวอย่างจะสำรวจมาสก์แกนที่ใช้งานอยู่และแจ้งให้ GameActivity ทราบเมื่อมีการใช้แกนใหม่ ซึ่งจะใช้ในฟังก์ชัน NativeEngine::CheckForNewAxis()
void NativeEngine::CheckForNewAxis() {
// Tell GameActivity about any new axis ids so it reports
// their events
const uint64_t activeAxisIds = Paddleboat_getActiveAxisMask();
uint64_t newAxisIds = activeAxisIds ^ mActiveAxisIds;
if (newAxisIds != 0) {
mActiveAxisIds = activeAxisIds;
int32_t currentAxisId = 0;
while(newAxisIds != 0) {
if ((newAxisIds & 1) != 0) {
LOGD("Enable Axis: %d", currentAxisId);
GameActivityPointerAxes_enableAxis(currentAxisId);
}
++currentAxisId;
newAxisIds >>= 1;
}
}
}
ตัวควบคุมการอ่าน
ไลบรารีเกมคอนโทรลเลอร์ใช้ค่าดัชนีเพื่ออ้างอิงถึงคอนโทรลเลอร์ที่เฉพาะเจาะจง ค่าดัชนีที่ถูกต้องจะอยู่ในช่วง 0 ถึง PADDLEBOAT_MAX_CONTROLLERS - 1 ฟังก์ชัน Paddleboat_getControllerStatus จะกำหนดสถานะของดัชนีตัวควบคุมที่ระบุ
Paddleboat_ControllerStatus Paddleboat_getControllerStatus(
const int32_t controllerIndex)
มีฟังก์ชัน 3 รายการสำหรับการอ่านข้อมูลจากตัวควบคุมที่เชื่อมต่อ
- ฟังก์ชัน
Paddleboat_getControllerNameจะดึงชื่อของอุปกรณ์ควบคุม - ฟังก์ชัน
Paddleboat_getControllerInfoจะดึงข้อมูลเกี่ยวกับอุปกรณ์ควบคุมเอง - ฟังก์ชัน
Paddleboat_getControllerDataจะดึงข้อมูลสถานะปัจจุบันของอินพุตตัวควบคุม
ชื่อตัวควบคุม
ฟังก์ชัน Paddleboat_getControllerName รับพารามิเตอร์อินพุต 3 รายการ ได้แก่ ดัชนีตัวควบคุม ขนาดบัฟเฟอร์ และตัวชี้ไปยังบัฟเฟอร์เพื่อจัดเก็บสตริงชื่อตัวควบคุม สตริงชื่อจะจัดรูปแบบเป็นสตริง C โดยใช้การเข้ารหัส UTF-8 ชื่อของอุปกรณ์จะได้รับภายในโดยใช้ InputDevice.getName()
หาก Paddleboat_getControllerName ดึงข้อมูลชื่อได้สำเร็จ ระบบจะแสดงผล PADDLEBOAT_NO_ERROR มิเช่นนั้นจะแสดงรหัสข้อผิดพลาดที่เหมาะสม
Paddleboat_ErrorCode Paddleboat_getControllerName(const int32_t controllerIndex,
const size_t bufferSize,
char *controllerName);
| พารามิเตอร์ | คำอธิบาย |
|---|---|
controllerIndex
|
ดัชนีของตัวควบคุมที่เริ่มการเรียกกลับ จะเป็นค่าระหว่าง 0 ถึง PADDLEBOAT_MAX_CONTROLLERS - 1 |
bufferSize
|
ขนาดเป็นไบต์ของบัฟเฟอร์ที่ส่งโดย controllerName ระบบจะตัดสตริงชื่อหากจำเป็นเพื่อให้พอดีกับบัฟเฟอร์ |
controllerName
|
ตัวชี้ไปยังบัฟเฟอร์ขนาด bufferSize ไบต์เพื่อจัดเก็บชื่อตัวควบคุม ระบบจะจัดเก็บชื่อเป็นสตริง C โดยใช้การเข้ารหัส UTF-8 |
ข้อมูลอุปกรณ์ควบคุม
ฟังก์ชัน Paddleboat_getControllerInfo จะใช้พารามิเตอร์อินพุต 2 รายการ ได้แก่ ดัชนีตัวควบคุมและตัวชี้ไปยังโครงสร้าง Paddleboat_Controller_Info
หาก Paddleboat_Controller_Info มีข้อมูลอยู่แล้ว Paddleboat_getControllerInfo จะแสดงผล PADDLEBOAT_NO_ERROR มิเช่นนั้นจะแสดงรหัสข้อผิดพลาดที่เหมาะสม
Paddleboat_ErrorCode Paddleboat_getControllerInfo(const int32_t controllerIndex,
Paddleboat_Controller_Info *controllerInfo)
โครงสร้าง Paddleboat_Controller_Info มีข้อมูลเฉพาะอุปกรณ์เกี่ยวกับตัวควบคุม
typedef struct Paddleboat_Controller_Info {
uint32_t controllerFlags;
int32_t controllerNumber;
int32_t vendorId;
int32_t productId;
int32_t deviceId;
Paddleboat_Controller_Thumbstick_Precision leftStickPrecision;
Paddleboat_Controller_Thumbstick_Precision rightStickPrecision;
} Paddleboat_Controller_Info;
typedef struct Paddleboat_Controller_Thumbstick_Precision {
float stickFlatX;
float stickFlatY;
float stickFuzzX;
float stickFuzzY;
} Paddleboat_Controller_Thumbstick_Precision;
สมาชิกโครงสร้างหลายรายการจะได้รับการป้อนข้อมูลด้วยค่าที่นำมาจาก InputDevice ที่เชื่อมโยงกับตัวควบคุม ดังนี้
controllerNumber - InputDevice.getControllerNumber()
vendorId - InputDevice.getVendorId()
productId - InputDevice.getProductId()
deviceId - InputDevice.getId()
- ค่า
stickFlatแสดงถึงขอบเขตของตำแหน่งแบนราบตรงกลาง ค่านี้มีประโยชน์เป็นหลักในการคำนวณ "เดดโซน" ตรงกลางเริ่มต้นในอุปกรณ์ที่ปรับศูนย์กลางอัตโนมัติ - ค่า
stickFuzzแสดงถึงความคลาดเคลื่อนที่ยอมรับได้ หรือค่าปัจจุบันอาจเบี่ยงเบนจากค่าจริงได้มากน้อยเพียงใดเนื่องจากสัญญาณรบกวนและข้อจำกัดด้านความไวของอุปกรณ์
ค่าทั้ง 2 ค่าจะได้รับการปรับให้เป็นมาตรฐานตามค่าแกนสูงสุดที่ 1.0 ในมิติข้อมูลใดมิติข้อมูลหนึ่ง
สมาชิก controllerFlags มีชุดค่าผสมของแฟล็กที่มาสก์บิตแต่ละรายการและค่าชุดค่าผสมหลายบิต
การดำเนินการ AND เชิงตรรกะของ controllerFlags ด้วย PADDLEBOAT_CONTROLLER_LAYOUT_MASK จะส่งผลให้เกิดค่าที่อาจแคสต์ไปยัง enum Paddleboat_ControllerButtonLayout Enum นี้ระบุไอคอนและเลย์เอาต์ของปุ่มที่ตัวควบคุมใช้
enum Paddleboat_ControllerButtonLayout {
// Y
// X B
// A
PADDLEBOAT_CONTROLLER_LAYOUT_STANDARD = 0,
// △
// □ ○
// x
PADDLEBOAT_CONTROLLER_LAYOUT_SHAPES = 1,
// X
// Y A
// B
PADDLEBOAT_CONTROLLER_LAYOUT_REVERSE = 2,
// X Y R1 L1
// A B R2 L2
PADDLEBOAT_CONTROLLER_LAYOUT_ARCADE_STICK = 3,
PADDLEBOAT_CONTROLLER_LAYOUT_MASK = 3
};
ค่าคงที่ต่อไปนี้จะกำหนดบิตความสามารถ หากต้องการตรวจสอบว่าตัวควบคุมรองรับความสามารถหนึ่งๆ หรือไม่ ให้ดำเนินการ AND เชิงตรรกะของค่าคงที่ที่เกี่ยวข้องกับ controllerFlags ผลลัพธ์ที่ไม่ใช่ 0 หมายความว่าตัวควบคุมรองรับความสามารถดังกล่าว
PADDLEBOAT_CONTROLLER_FLAG_TOUCHPAD
หากตั้งค่าบิตแฟล็กนี้ ตัวควบคุมจะมีทัชแพดในตัว หากกดทัชแพด ตัวควบคุมจะตั้งค่าบิต PADDLEBOAT_BUTTON_TOUCHPAD ในช่อง Paddleboat_Controller_Data.buttonsDown
PADDLEBOAT_CONTROLLER_FLAG_VIRTUAL_MOUSE
หากตั้งค่าบิตแฟล็กนี้ ตัวควบคุมจะจำลองอุปกรณ์ชี้ตำแหน่ง ระบบจะป้อนพิกัดปัจจุบันของตัวชี้เสมือนลงในสมาชิก virtualPointer ของโครงสร้าง Paddleboat_Controller_Data
ข้อมูลผู้ควบคุม
ฟังก์ชัน Paddleboat_getControllerData จะใช้พารามิเตอร์อินพุต 2 รายการ ได้แก่ ดัชนีตัวควบคุมและตัวชี้ไปยังโครงสร้าง Paddleboat_Controller_Data หาก Paddleboat_Controller_Data มีข้อมูลอยู่ Paddleboat_getControllerData จะแสดงผลเป็น PADDLEBOAT_NO_ERROR มิเช่นนั้นระบบจะแสดงรหัสข้อผิดพลาดที่เหมาะสม
Paddleboat_ErrorCode Paddleboat_getControllerData(const int32_t controllerIndex,
Paddleboat_Controller_Data *controllerData)
โครงสร้าง Paddleboat_Controller_Data มีค่าอินพุตการควบคุมปัจจุบันของตัวควบคุม
typedef struct Paddleboat_Controller_Data {
uint64_t timestamp;
uint32_t buttonsDown;
Paddleboat_Controller_Thumbstick leftStick;
Paddleboat_Controller_Thumbstick rightStick;
float triggerL1;
float triggerL2;
float triggerR1;
float triggerR2;
Paddleboat_Controller_Pointer virtualPointer;
} Paddleboat_Controller_Data;
typedef struct Paddleboat_Controller_Pointer {
float pointerX;
float pointerY;
} Paddleboat_Controller_Pointer;
typedef struct Paddleboat_Controller_Thumbstick {
float stickX;
float stickY;
} Paddleboat_Controller_Thumbstick;
ช่วงค่า
| ประเภทอินพุต | ช่วงค่า |
|---|---|
| แกนปุ่มทัมบ์สติ๊ก | -1.0 ถึง 1.0 |
| ทริกเกอร์ | 0.0 ถึง 1.0 |
| เคอร์เซอร์เสมือนจริง | 0.0 เป็นความกว้าง/ความสูงของหน้าต่าง (เป็นพิกเซล) |
รายละเอียดโครงสร้าง
| สมาชิกในบ้าน | คำอธิบาย |
|---|---|
buttonsDown
|
อาร์เรย์บิตฟิลด์แบบบิตต่อปุ่ม ค่าคงที่บิตมาสก์ของปุ่มจะกำหนดไว้ในไฟล์ส่วนหัว paddleboat.h และขึ้นต้นด้วย PADDLEBOAT_BUTTON_ |
timestamp
|
การประทับเวลาของเหตุการณ์อินพุตของตัวควบคุมล่าสุด การประทับเวลาคือไมโครวินาทีนับตั้งแต่ Epoch ของนาฬิกา |
virtualPointer
|
ตำแหน่งเคอร์เซอร์เสมือน ใช้ได้เฉพาะเมื่อตั้งค่าแฟล็ก PADDLEBOAT_CONTROLLER_FLAG_VIRTUAL_MOUSE ใน controllerFlags เท่านั้น มิฉะนั้นจะเป็น 0.0, 0.0 |