Fungsi ScriptShape (usp10.h)
Menghasilkan glyph dan atribut visual untuk eksekusi Unicode.
Sintaks
HRESULT ScriptShape(
[in] HDC hdc,
[in, out] SCRIPT_CACHE *psc,
[in] const WCHAR *pwcChars,
[in] int cChars,
[in] int cMaxGlyphs,
[in, out] SCRIPT_ANALYSIS *psa,
[out] WORD *pwOutGlyphs,
[out] WORD *pwLogClust,
[out] SCRIPT_VISATTR *psva,
[out] int *pcGlyphs
);
Parameter
[in] hdc
Pilihan. Menangani konteks perangkat. Untuk informasi selengkapnya, lihat Penembolokan.
[in, out] psc
Arahkan ke struktur SCRIPT_CACHE yang mengidentifikasi cache skrip.
[in] pwcChars
Penunjuk ke array karakter Unicode yang menentukan eksekusi.
[in] cChars
Jumlah karakter dalam eksekusi Unicode.
[in] cMaxGlyphs
Jumlah maksimum glyph yang akan dihasilkan, dan panjang pwOutGlyphs. Nilai yang wajar adalah (1.5 * cChars + 16), tetapi nilai ini mungkin tidak cukup dalam beberapa keadaan. Untuk informasi lebih lanjut, lihat bagian Keterangan.
[in, out] psa
Arahkan ke struktur SCRIPT_ANALYSIS untuk eksekusi, yang berisi hasil dari panggilan sebelumnya ke ScriptItemize.
[out] pwOutGlyphs
Pointer ke buffer di mana fungsi ini mengambil array glyph dengan ukuran seperti yang ditunjukkan oleh cMaxGlyphs.
[out] pwLogClust
Pointer ke buffer di mana fungsi ini mengambil array informasi kluster logis. Setiap elemen array sesuai dengan karakter dalam array karakter Unicode; oleh karena itu array ini memiliki jumlah elemen yang ditunjukkan oleh cChars. Nilai setiap elemen adalah offset dari glyph pertama dalam eksekusi ke glyph pertama dalam kluster yang berisi karakter yang sesuai. Perhatikan bahwa, ketika anggota fRTL diatur ke TRUE dalam struktur SCRIPT_ANALYSIS , elemen berkurang saat array dibaca.
[out] psva
Pointer ke buffer di mana fungsi ini mengambil array struktur SCRIPT_VISATTR yang berisi informasi atribut visual. Karena setiap glyph hanya memiliki satu atribut visual, array ini memiliki jumlah elemen yang ditunjukkan oleh cMaxGlyphs.
[out] pcGlyphs
Pointer ke lokasi di mana fungsi ini mengambil jumlah glyph yang ditunjukkan dalam pwOutGlyphs.
Nilai kembali
Mengembalikan 0 jika berhasil. Fungsi mengembalikan nilai HRESULT bukan nol jika tidak berhasil. Dalam semua kasus kesalahan, konten semua parameter output tidak terdefinisi.
Pengembalian kesalahan meliputi:
- E_OUTOFMEMORY. Panjang buffer output yang ditunjukkan oleh cMaxGlyphs tidak mencukupi.
- E_PENDING. Cache skrip yang ditentukan oleh parameter psc tidak berisi informasi yang cukup untuk membentuk string, dan konteks perangkat telah diteruskan sebagai NULL sehingga fungsi tidak dapat menyelesaikan proses pembentukan. Aplikasi harus menyiapkan konteks perangkat yang benar untuk eksekusi, dan memanggil fungsi ini lagi dengan nilai yang sesuai dalam hdc dan dengan semua parameter lain yang sama.
- USP_E_SCRIPT_NOT_IN_FONT. Font yang sesuai dengan konteks perangkat tidak mendukung skrip yang diperlukan oleh eksekusi yang ditunjukkan oleh pwcChars. Aplikasi harus memilih font lain, menggunakan ScriptGetCMap atau fungsi lain untuk memilih font.
Keterangan
Lihat Menampilkan Teks dengan Uniscribe untuk diskusi konteks di mana fungsi ini biasanya dipanggil.
Jika fungsi ini mengembalikan E_OUTOFMEMORY, aplikasi mungkin memanggil ScriptShape berulang kali, dengan buffer output yang berturut-turut lebih besar, sampai buffer yang cukup besar disediakan. Jumlah glyph yang dihasilkan oleh titik kode bervariasi sesuai dengan skrip dan font. Untuk skrip sederhana, titik kode Unicode mungkin menghasilkan satu glyph. Namun, font skrip yang kompleks mungkin membuat karakter dari komponen, dan dengan demikian menghasilkan beberapa kali glyph sebagai karakter. Selain itu, ada kasus khusus, seperti representasi karakter yang tidak valid, di mana glyph tambahan ditambahkan untuk mewakili urutan yang tidak valid. Oleh karena itu, tebakan yang wajar untuk ukuran buffer yang ditunjukkan oleh pwOutGlyphs adalah 1,5 kali panjang buffer karakter, ditambah 16 glyph tambahan untuk kasus yang jarang terjadi, misalnya, representasi urutan yang tidak valid.
Fungsi ini dapat mengatur anggota fNoGlyphIndex dari struktur SCRIPT_ANALYSIS jika font atau sistem operasi tidak dapat mendukung indeks glyph.
Aplikasi dapat memanggil ScriptShape untuk menentukan apakah font mendukung karakter dalam string tertentu. Jika fungsi mengembalikan S_OK, aplikasi harus memeriksa output untuk glyph yang hilang. Jika fLogicalOrder diatur ke TRUE dalam struktur SCRIPT_ANALYSIS , fungsi selalu menghasilkan glyph dalam urutan yang sama dengan karakter Unicode asli. Jika fLogicalOrder diatur ke FALSE, fungsi menghasilkan item kanan-ke-kiri dalam urutan terbalik sehingga ScriptTextOut tidak harus membalikkannya sebelum memanggil ExtTextOut.
Jika anggota eScriptSCRIPT_ANALYSIS diatur ke SCRIPT_UNDEFINED, pembentukan dinonaktifkan. Dalam hal ini, ScriptShape menampilkan glyph yang ada dalam tabel cmap font. Jika tidak ada glyph dalam tabel, fungsi menunjukkan bahwa glyph hilang.
ScriptShape mengurutkan kluster secara seragam dalam eksekusi, dan mengurutkan glyph secara seragam dalam kluster. Ini menggunakan nilai anggota fRTLSCRIPT_ANALYSIS, dari ScriptItemize, untuk mengidentifikasi pengurutan sebagai kiri-ke-kanan atau kanan-ke-kiri.
Contoh
Contoh berikut menunjukkan bagaimana ScriptShape menghasilkan array kluster logis (pwLogClust) dari array karakter (pwcChars) dan array glyph (pwOutGlyphs). Eksekusi memiliki empat kluster.
- Kluster pertama: satu karakter yang diwakili oleh satu glyph
- Kluster kedua: satu karakter diwakili oleh tiga glyph
- Kluster ketiga: tiga karakter yang diwakili oleh satu glyph
- Kluster keempat: dua karakter diwakili oleh tiga glyph
- | c1u1 | c2u1 | c3u1 c3u2 c3u3 | c4u1 c4u2 |
- | c1g1 | c2g1 c2g2 c2g3 | c3g1 | c4g1 c4g2 c4g3 |
- | 0 | 1 | 4 4 4 | 5 5 |
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung | Windows 2000 Professional [hanya aplikasi desktop] |
| Server minimum yang didukung | Windows 2000 Server [hanya aplikasi desktop] |
| Target Platform | Windows |
| Header | usp10.h |
| Pustaka | Usp10.lib |
| DLL | Usp10.dll |