Fungsi ScriptShape (usp10.h)

Artikel
08/26/2023

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.

Penting Dimulai dengan Windows 8: Untuk mempertahankan kemampuan untuk berjalan pada Windows 7, modul yang menggunakan Uniscribe harus menentukan Usp10.lib sebelum gdi32.lib dalam daftar pustakanya.

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

Array karakter, di mana c<n>u<m> berarti kluster n, titik kode Unicode m:

| c1u1 | c2u1 | c3u1 c3u2 c3u3 | c4u1 c4u2 |

Array Glyph, di mana c<n>g<m> berarti kluster n, glyph m:

| c1g1 | c2g1 c2g2 c2g3 | c3g1 | c4g1 c4g2 c4g3 |

Array kluster, yaitu, offset (dalam glyph) ke kluster yang berisi karakter:

| 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