Dukungan Senter

Mulai dari Windows Threshold, kami akan mengekspos API WinRT Lamp baru yang memungkinkan seseorang memprogram flash kamera tanpa perlu membuat instans Windows.Media.Capture.MediaCapture . Dengan demikian, pengembang dapat menulis aplikasi senter (hanya untuk tujuan iluminasi) dengan menggambar sedikitnya jumlah sumber daya, termasuk daya, sehingga perangkat komputasi dapat dioptimalkan untuk masa pakai dan performa baterai.

Untuk mencapai hal ini, IHV/OEM harus menerapkan driver WDM yang mendukung fungsi berikut:

  • Perbolehkan sistem menghitung semua perangkat flash.

  • Aktifkan/matikan senter berdasarkan per perangkat.

  • Jika berlaku, sesuaikan intensitas cahaya (mirip dengan PowerPercent) berdasarkan per perangkat.

  • Jika berlaku, tentukan warna terang berdasarkan per perangkat.

Dalam hal fungsionalitas, daftar di atas tumpang tindih secara signifikan dengan MediaCapture (misalnya, FlashControl dan TorchControl). Selain itu, perangkat keras flash yang sama sedang digunakan untuk lampu dan flash-during-capture. Akibatnya, disarankan agar IHV/OEM mendukung kedua jenis operasi dengan mengontrol flash secara eksklusif menggunakan satu driver WDM. Gambar di bawah ini menggambarkan konsep:

Diagram konsep kontrol lampu kilat eksklusif.

Dalam contoh di atas, hanya ada satu instans perangkat keras flash (seperti yang ditampilkan) dan dikelola oleh satu driver flash KMDF. Driver flash mengekspos dua antarmuka perangkat, yang masing-masing ditargetkan untuk jenis klien tertentu (atau WinRT API). Misalnya, mengingat gambar di atas:

  • WinRT MediaCapture API dan minidriver AVStream selalu berkomunikasi dengan driver flash melalui antarmuka GUID_DEVINTERFACE_CAMERA_FLASH, sedangkan

  • WINRT Lamp API selalu berkomunikasi dengan flash driver melalui antarmuka GUID_DEVINTERFACE_LAMP.

Karena antarmuka GUID_DEVINTERFACE_CAMERA_FLASH digunakan oleh minidriver AVStream khusus vendor, IHV/OEM bebas untuk menentukan fungsi sesuai keinginan mereka – tidak ada batasan yang dikenakan oleh Windows.

Namun, Microsoft akan menstandarkan antarmuka, GUID_DEVINTERFACE_LAMP, karena akan digunakan oleh WINRT Lamp API. Untuk informasi selengkapnya tentang GUID_DEVINTERFACE_LAMP, lihat GUID Kelas Antarmuka Perangkat

Kasus Penggunaan Konkurensi

Berbagi Flash antara Aplikasi Kamera dan Senter

Lampu kilat kamera biasanya dianggap sebagai periferal sekunder ke perangkat tangkapan. Ini tidak dimaksudkan untuk dibagikan dengan skenario tanpa kamera selama proses pengambilan. Untuk mempersulit lebih lanjut, jumlah perangkat flash pada sasis sangat terbatas sedemikian rupa sehingga, dalam praktiknya, tidak akan ada lampu kilat cadangan yang didedikasikan untuk tujuan senter saja.

Dari perspektif perangkat lunak, ada tantangan tersendiri di mana aplikasi kamera dan aplikasi senter dapat hidup berdampingan dan mengakses kilat/flash secara bersamaan. Misalnya, secara teori, pengguna dapat beralih status LED melalui aplikasi senter saat jendela bidik kamera berjalan.

Karena kamera memerlukan kontrol yang tepat atas lampu kilat untuk mendukung fokus dan pengambilan, mungkin sulit bagi driver untuk menyelesaikan permintaan lampu kilat kepentingan yang bertentangan sambil memastikan kualitas gambar. Untuk mengatasi masalah ini, kebijakan berikut diberlakukan pada tingkat sistem sebagai kontrak:

  • Jika sesi pengambilan dimulai terlebih dahulu, aplikasi senter tidak dapat memanipulasi lampu kilat hingga pengambilan berhenti.

    • Aplikasi senter masih dapat memperoleh handle ke driver flash tetapi operasi apa pun yang memodifikasi status flash menghasilkan kesalahan instan.

    • Ketika pemotretan berhenti sehingga minidriver AVStream melepaskan flash, driver flash diwajibkan untuk memposting pemberitahuan PnP (lihat GUID_LAMP_RESOURCES_AVAILABLE pada bagian Pemberitahuan Asinkron) yang menunjukkan bahwa perangkat keras yang mendasar kini telah tersedia. Ketika menerima notifikasi semacam itu, aplikasi senter dapat memprogram kilatan sesuai.

  • Jika aplikasi senter dimulai terlebih dahulu, sesi pemotretan bebas untuk membajak perangkat keras flash tanpa persetujuan yang jelas.

    • Dengan "membajak", artinya IHV/OEM dapat menerapkan protokol sembarang (mungkin melalui antarmuka GUID_DEVINTERFACE_CAMERA_FLASH) sehingga minidriver AVStream diizinkan untuk mengakses flash seolah-olah perangkat keras tidak digunakan sama sekali.

    • Ketika pembajakan terjadi, driver flash diperlukan untuk memposting pemberitahuan PnP lain (lihat GUID_LAMP_RESOURCES_LOST di Pemberitahuan Asinkron) yang menunjukkan flash telah secara tidak sengaja ditetapkan ulang sedemikian rupa sehingga aplikasi senter dapat bertindak sesuai (dengan memperbarui UI misalnya)

Berbagi Lampu Kilat antara Beberapa Aplikasi Senter

Jika kamera tidak terlibat dan dua aplikasi senter berjalan berturut-turut, driver harus terus melayani klien pertama yang telah memperoleh antarmuka GUID_DEVINTERFACE_LAMP dan menolak semua klien tambahan sampai yang pertama merilis antarmuka pada akhirnya.

Dengan kata lain, antarmuka GUID_DEVINTERFACE_LAMP hanya memungkinkan satu aplikasi senter pada satu waktu dan klien pertama yang memperoleh antarmuka mencegah klien lain berjalan (kamera/AVStream dikecualikan).

GUID Kelas Antarmuka Perangkat

Driver flash IHV/OEM yang mampu mendukung fungsi lampu senter tanpa tergantung pada MediaCapture harus mendaftarkan dirinya dengan GUID Kelas Antarmuka Perangkat, GUID_DEVINTERFACE_LAMP.

Karakteristik Pengaturan
Pengidentifikasi GUID_DEVINTERFACE_LAMP
GUID Kelas {6C11E9E3-8232-4F0A-AD19-AAEC26CA5E98}

GUID kelas antarmuka perangkat GUID_DEVINTERFACE_CAMERA_FLASH dapat ditentukan khusus oleh IHV/OEM. Namun, GUID dari kelas antarmuka perangkat GUID_DEVINTERFACE_LAMP ditentukan oleh Windows.

Berdasarkan kontrak, driver yang mengekspos antarmuka perangkat, GUID_DEVINTERFACE_LAMP, diperlukan untuk mendukung fungsi berikut (lihat bagian selanjutnya untuk detailnya):

  • IOCTL_LAMP_GET_CAPABILITIES_{WHITE|COLOR} – mendapatkan semua mode (misalnya, putih-saja vs. warna) yang didukung oleh perangkat keras yang mendasar

  • IOCTL_LAMP_{GET|SET}_MODE – mendapatkan atau mengatur mode saat ini

  • IOCTL_LAMP_{GET|SET}_INTENSITY_{WHITE|COLOR} – mendapatkan atau mengatur intensitas cahaya

  • IOCTL_LAMP_{GET|SET}_EMITTING_LIGHT – mendapatkan atau mengatur status lampu kilat (misalnya, ON/OFF)

Jika perangkat memiliki lebih dari satu perangkat keras flash dari berbagai jenis (misalnya, LED putih dan lampu kilat Xenon) dan perangkat keras ini dikontrol oleh driver flash yang berbeda, setiap driver akan mengekspos antarmuka GUID_DEVINTERFACE_LAMP yang sama dengan ID instans yang unik.

Properti Antarmuka Perangkat

Karena perangkat komputasi dapat memiliki nol atau lebih perangkat flash di panel yang berbeda, WINRT Lamp API memerlukan mekanisme untuk menghitung semua perangkat keras flash sehingga aplikasi dapat memprogram instans tertentu.

Untuk mendukung enumerasi perangkat, mirip dengan driver kamera, driver flash diperlukan untuk mengaitkan struktur ACPI _PLD v2 dengan setiap antarmuka GUID_DEVINTERFACE_LAMP sebagai data properti antarmuka.

IOCTL_LAMP_GET_CAPABILITIES_WHITE

Permintaan I/O IOCTL_LAMP_GET_CAPABILITIES_WHITE meminta kemampuan lampu kilat saat perangkat dikonfigurasi untuk memancarkan cahaya putih.

Definisi

#define IOCTL_LAMP_BASE FILE_DEVICE_UNKNOWN
#define IOCTL_LAMP_GET_CAPABILITIES_WHITE \
    CTL_CODE(IOCTL_LAMP_BASE, 0x0000, METHOD_BUFFERED, FILE_ANY_ACCESS)

Parameter Masukan

Irp->AssociatedIrp.SystemBuffer menunjuk ke buffer jenis LAMP_CAPABILITIES_WHITE. Lihat Komentar untuk detailnya.

IO_STACK_LOCATION.Parameters.DeviceIoControl.OutputBufferLength adalah panjang buffer (dalam byte) yang diteruskan di bidang >Irp-AssociatedIrp.SystemBuffer.

Parameter Keluaran

Irp-AssociatedIrp.SystemBuffer> diisi dengan semua kemampuan yang didukung oleh perangkat keras flash.

Blok Status I/O

Driver mengatur Irp-IoStatus.Status> ke STATUS_SUCCESS atau status kesalahan yang sesuai. Ini akan mengatur Irp-IoStatus.Information> ke jumlah byte yang diperlukan untuk menahan buffer.

Komentar

Berdasarkan persyaratan, flash yang drivernya mendukung antarmuka GUID_DEVINTERFACE_LAMP diperlukan untuk mendukung memancarkan cahaya putih. Payload IOCTL ini didefinisikan sebagai berikut:

// The output parameter type of IOCTL_LAMP_GET_CAPABILITIES_WHITE.
typedef struct LAMP_CAPABILITIES_WHITE
{
    BOOLEAN IsLightIntensityAdjustable;
} LAMP_CAPABILITIES_WHITE;

Bidang IsLightIntensityAdjustable menunjukkan apakah tingkat kecerahan dapat diprogram. Jika bidang ini mengevaluasi salah, berarti perangkat dasar ini hanya mendukung sakelar nyala/mati dan intensitas cahaya tidak dapat disesuaikan.

IOCTL_LAMP_GET_CAPABILITIES_COLOR

Permintaan I/O IOCTL_LAMP_GET_CAPABILITIES_COLOR meminta kemampuan flash saat perangkat dikonfigurasi untuk memancarkan cahaya warna.

Definisi

#define IOCTL_LAMP_GET_CAPABILITIES_COLOR \
    CTL_CODE(IOCTL_LAMP_BASE, 0x0001, METHOD_BUFFERED, FILE_ANY_ACCESS)

Parameter Masukan

Irp->AssociatedIrp.SystemBuffer menunjuk ke buffer tipe LAMP_CAPABILITIES_COLOR. Lihat Komentar untuk detailnya.

IO_STACK_LOCATION.Parameters.DeviceIoControl.OutputBufferLength adalah panjang buffer (dalam byte) yang diteruskan di bidang Irp->AssociatedIrp.SystemBuffer.

Parameter Keluaran

Irp-AssociatedIrp.SystemBuffer> dilengkapi dengan semua kemampuan yang didukung oleh perangkat keras flash.

Blok Status I/O

Driver mengatur Irp-IoStatus.Status> ke STATUS_SUCCESS atau status kesalahan yang sesuai. Ini akan mengatur Irp-IoStatus.Information> ke jumlah byte yang diperlukan untuk menahan buffer.

Komentar

Payload IOCTL ini didefinisikan sebagai berikut:

// The output parameter type of IOCTL_LAMP_GET_CAPABILITIES_COLOR.
typedef struct LAMP_CAPABILITIES_COLOR
{
    BOOLEAN IsSupported;
    BOOLEAN IsLightIntensityAdjustable;
} LAMP_CAPABILITIES_COLOR;

Bidang pertama, IsSupported, menunjukkan apakah lampu kilat dapat memancarkan cahaya warna. Jika perangkat keras tidak mendukung lampu warna, pengandar harus mengatur bidang ini ke false.

Bidang kedua, IsLightIntensityAdjustable, menunjukkan apakah tingkat luminance dapat diprogram. Jika lampu kilat tidak mendukung cahaya warna (misalnya, IsSupported bernilai salah), klien harus membuang nilai IsLightIntensityAdjustable.

IOCTL_LAMP_GET_MODE

Permintaan I/O IOCTL_LAMP_GET_MODE memeriksa mode yang saat ini dikonfigurasi untuk lampu kilat.

Definisi

#define IOCTL_LAMP_GET_MODE \
    CTL_CODE(IOCTL_LAMP_BASE, 0x0002, METHOD_BUFFERED, FILE_ANY_ACCESS)

Parameter Masukan

Irp-AssociatedIrp.SystemBuffer> menunjuk ke buffer jenis LAMP_MODE, yang didefinisikan sebagai berikut:

typedef enum LAMP_MODE
{
    LAMP_MODE_WHITE = 0,
    LAMP_MODE_COLOR
} LAMP_MODE;

IO_STACK_LOCATION.Parameters.DeviceIoControl.OutputBufferLength adalah panjang buffer (dalam byte) yang diteruskan pada bidang Irp-AssociatedIrp.SystemBuffer>.

Parameter Keluaran

Irp-AssociatedIrp.SystemBuffer> diisi dengan nilai LAMP_MODE.

Blok Status I/O

Driver mengatur Irp-IoStatus.Status> ke STATUS_SUCCESS atau status kesalahan yang sesuai. Ini akan mengatur Irp->IoStatus.Information ke jumlah byte yang diperlukan untuk menyimpan nilai DWORD.

Jika sesi MediaCapture sedang melakukan streaming data pada saat permintaan ini dibuat, driver harus mengembalikan kesalahan (STATUS_RESOURCE_IN_USE) melalui Irp->IoStatus.Status.

IOCTL_LAMP_SET_MODE

Permintaan I/O IOCTL_LAMP_SET_MODE mengatur mode tempat lampu kilat beroperasi.

Definisi

#define IOCTL_LAMP_SET_MODE \
    CTL_CODE(IOCTL_LAMP_BASE, 0x0003, METHOD_BUFFERED, FILE_ANY_ACCESS)

Parameter Masukan

Irp->AssociatedIrp.SystemBuffer menunjuk ke buffer tipe LAMP_MODE.

Parameter Keluaran

Tidak ada.

Blok Status I/O

Driver mengatur Irp-IoStatus.Status> ke STATUS_SUCCESS atau status kesalahan yang sesuai.

Jika sesi MediaCapture sedang melakukan streaming data pada saat permintaan ini dibuat, driver harus mengembalikan kesalahan (STATUS_RESOURCE_IN_USE) melalui >Irp-IoStatus.Status.

IOCTL_LAMP_GET_INTENSITY_WHITE (Mendapatkan Intensitas Lampu Putih)

Permintaan I/O IOCTL_LAMP_GET_INTENSITY_WHITE mengkueri intensitas cahaya saat lampu kilat dikonfigurasi untuk memancarkan cahaya putih.

Definisi

#define IOCTL_LAMP_GET_INTENSITY_WHITE \
    CTL_CODE(IOCTL_LAMP_BASE, 0x0004, METHOD_BUFFERED, FILE_ANY_ACCESS)

Parameter Masukan

Irp->AssociatedIrp.SystemBuffer menunjuk ke struktur LAMP_INTENSITY_WHITE. Lihat Komentar untuk detailnya.

IO_STACK_LOCATION.Parameters.DeviceIoControl.OutputBufferLength adalah panjang buffer (dalam byte) yang diteruskan di bidang Irp->AssociatedIrp.SystemBuffer.

Parameter Keluaran

Irp-AssociatedIrp.SystemBuffer> diisi dengan informasi intensitas cahaya.

Blok Status I/O

Driver mengatur Irp-IoStatus.Status> ke STATUS_SUCCESS atau status kesalahan yang sesuai.

Jika sesi MediaCapture sedang melakukan streaming data pada saat permintaan ini dibuat, driver harus mengembalikan kesalahan (STATUS_RESOURCE_IN_USE) melalui Irp-IoStatus.Status>.

Komentar

Jenis payload IOCTL ini didefinisikan sebagai berikut:

// The I/O parameter type of IOCTL_LAMP_{GET|SET}_INTENSITY_WHITE.
typedef struct LAMP_INTENSITY_WHITE
{
    BYTE Value;
} LAMP_INTENSITY_WHITE;

Bidang Nilai adalah intensitas cahaya putih dalam persentase antara 0 dan 100 inklusif.

IOCTL_LAMP_SET_INTENSITY_WHITE

Permintaan I/O IOCTL_LAMP_SET_INTENSITY_WHITE mengatur lampu kilat ke intensitas cahaya yang ditentukan.

Definisi

#define IOCTL_LAMP_SET_INTENSITY_WHITE \
    CTL_CODE(IOCTL_LAMP_BASE, 0x0005, METHOD_BUFFERED, FILE_ANY_ACCESS)

Parameter Masukan

Irp->AssociatedIrp.SystemBuffer menunjuk ke struktur LAMP_INTENSITY_WHITE, lihat IOCTL_LAMP_GET_INTENSITY_WHITE untuk lebih jelasnya.

Parameter Keluaran

Tidak ada.

Blok Status I/O

Driver mengatur Irp-IoStatus.Status> ke STATUS_SUCCESS atau status kesalahan yang sesuai.

Jika sesi MediaCapture sedang melakukan streaming data pada saat permintaan ini dibuat, driver harus mengembalikan kesalahan (STATUS_RESOURCE_IN_USE) melalui Irp-IoStatus.Status>.

IOCTL_LAMP_GET_INTENSITY_COLOR

Permintaan I/O IOCTL_LAMP_GET_INTENSITY_COLOR mengkueri intensitas cahaya saat lampu kilat dikonfigurasi untuk memancarkan cahaya warna.

Definisi

#define IOCTL_LAMP_GET_INTENSITY_COLOR \
    CTL_CODE(IOCTL_LAMP_BASE, 0x0006, METHOD_BUFFERED, FILE_ANY_ACCESS)

Parameter Masukan

Irp-AssociatedIrp.SystemBuffer> menunjuk ke struktur LAMP_INTENSITY_COLOR. Lihat Komentar untuk detailnya.

IO_STACK_LOCATION.Parameters.DeviceIoControl.OutputBufferLength adalah panjang buffer (dalam byte) yang diteruskan di bidang Irp->AssociatedIrp.SystemBuffer.

Parameter Keluaran

Irp-AssociatedIrp.SystemBuffer> diisi dengan informasi intensitas cahaya.

Blok Status I/O

Driver mengatur Irp-IoStatus.Status> ke STATUS_SUCCESS atau status kesalahan yang sesuai.

Jika sesi MediaCapture sedang melakukan streaming data pada saat permintaan ini dibuat, driver harus mengembalikan kesalahan (STATUS_RESOURCE_IN_USE) melalui Irp-IoStatus.Status>.

Komentar

Jenis payload IOCTL ini didefinisikan sebagai berikut:

// The I/O parameter type of IOCTL_LAMP_{GET|SET}_INTENSITY_COLOR.
typedef struct LAMP_INTENSITY_COLOR
{
    BYTE Red; // Red light intensity in percentage (0-100)
    BYTE Green; // Green light intensity in percentage (0-100)
    BYTE Blue; // Blue light intensity in percentage (0-100)
} LAMP_INTENSITY_COLOR;

IOCTL_LAMP_SET_INTENSITY_COLOR

Permintaan I/O IOCTL_LAMP_SET_INTENSITY_COLOR mengatur lampu kilat ke intensitas cahaya yang ditentukan.

Definisi

#define IOCTL_LAMP_SET_INTENSITY_COLOR \
    CTL_CODE(IOCTL_LAMP_BASE, 0x0007, METHOD_BUFFERED, FILE_ANY_ACCESS)

Parameter Masukan

Irp-AssociatedIrp.SystemBuffer> menunjuk ke struktur LAMP_INTENSITY_COLOR (lihat IOCTL_LAMP_GET_INTENSITY_COLOR untuk detailnya).

Parameter Keluaran

Tidak ada.

Blok Status I/O

Driver mengatur Irp-IoStatus.Status> ke STATUS_SUCCESS atau status kesalahan yang sesuai.

Jika sesi MediaCapture sedang melakukan streaming data pada saat permintaan ini dibuat, driver harus mengembalikan kesalahan (STATUS_RESOURCE_IN_USE) melalui Irp-IoStatus.Status>.

IOCTL_LAMP_GET_EMITTING_LIGHT

Permintaan I/O IOCTL_LAMP_GET_EMITTING_LIGHT akan memeriksa apakah lampu (lampu kilat) sedang dinyalakan.

Definisi

#define IOCTL_LAMP_GET_EMITTING_LIGHT
    CTL_CODE(IOCTL_LAMP_BASE, 0x0008, METHOD_BUFFERED, FILE_ANY_ACCESS)

Parameter Masukan

Irp->AssociatedIrp.SystemBuffer menunjuk ke buffer tipe BOOLEAN.

IO_STACK_LOCATION.Parameters.DeviceIoControl.OutputBufferLength adalah panjang buffer (dalam byte) yang diteruskan di bidang Irp->AssociatedIrp.SystemBuffer.

Parameter Keluaran

Irp-AssociatedIrp.SystemBuffer> diisi dengan status lampu kilat: TRUE berarti lampu kilat menyala (misalnya, memancarkan cahaya); FALSE berarti sebaliknya.

Blok Status I/O

Driver mengatur Irp-IoStatus.Status> ke STATUS_SUCCESS atau status kesalahan yang sesuai. Ini akan mengatur Irp->IoStatus.Information ke jumlah byte yang diperlukan untuk menyimpan nilai DWORD.

Jika sesi MediaCapture sedang melakukan streaming data pada saat permintaan ini dibuat, driver harus mengembalikan kesalahan (STATUS_RESOURCE_IN_USE) melalui Irp-IoStatus.Status>.

IOCTL_LAMP_SET_EMITTING_LIGHT

Perintah I/O IOCTL_LAMP_SET_EMITTING_LIGHT menyalakan/mematikan lampu kilat.

Definisi

#define IOCTL_LAMP_SET_EMITTING_LIGHT
    CTL_CODE(IOCTL_LAMP_BASE, 0x0009, METHOD_BUFFERED, FILE_ANY_ACCESS)

Parameter Masukan

Irp-AssociatedIrp.SystemBuffer> menunjuk ke buffer jenis BOOLEAN dengan TRUE yang menunjukkan ON; FALSE jika sebaliknya.

Parameter Keluaran

Tidak ada.

Blok Status I/O

Driver mengatur Irp-IoStatus.Status> ke STATUS_SUCCESS atau status kesalahan yang sesuai.

Jika sesi MediaCapture sedang melakukan streaming data pada saat permintaan ini dibuat, driver harus mengembalikan kesalahan (STATUS_RESOURCE_IN_USE) melalui Irp-IoStatus.Status>.

Pemberitahuan Asinkron

Seperti yang dijelaskan dalam Kasus Penggunaan Konkurensi, driver flash diperlukan untuk mengirim pemberitahuan PnP untuk melaporkan ketersediaan sumber daya. Ini dapat dilakukan dengan memanggil IoReportTargetDeviceChange (atau IoReportTargetDeviceChangeAsynchronous) dengan GUID berikut tergantung pada skenario:

  • Sumber daya kilat telah dinonaktifkan karena sesi pemotretan (atau aplikasi senter lainnya) dijalankan.

    Karakteristik Pengaturan
    Pengidentifikasi GUID_LAMP_RESOURCES_LOST
    GUID Kelas {F770E98C-4403-48C9-B1D2-4EEC3302E41F}

  • Sumber daya flash sekarang telah tersedia:

    Karakteristik Pengaturan
    Pengidentifikasi GUID_LAMP_RESOURCES_AVAILABLE
    GUID Kelas {185FE7CE-2616-481B-9094-20BB893ACD81}
  • Last updated on