DirectXTex

ไลบรารีการประมวลผลพื้นผิว DirectXTex

http://go.microsoft.com/fwlink/?LinkId=248926

ลิขสิทธิ์ (c) Microsoft Corporation

28 ตุลาคม 2024

แพ็คเกจนี้ประกอบด้วย DirectXTex ซึ่งเป็นไลบรารีซอร์สที่ใช้ร่วมกันสำหรับการอ่านและเขียนไฟล์ .DDS และดำเนินการประมวลผลเนื้อหาพื้นผิวต่างๆ รวมถึงการปรับขนาด การแปลงรูปแบบ การสร้าง mip-map การบีบอัดบล็อกสำหรับทรัพยากรพื้นผิวรันไทม์ Direct3D และแผนที่ความสูงเป็นปกติ การแปลงแผนที่ ไลบรารีนี้ใช้ Windows Image Component (WIC) API นอกจากนี้ยังมีตัวอ่านและตัวเขียน .TGA และ .HDR เนื่องจากรูปแบบไฟล์ภาพเหล่านี้มักใช้สำหรับไปป์ไลน์การประมวลผลเนื้อหาพื้นผิว แต่ตัวแปลงสัญญาณ WIC ในตัวยังไม่รองรับในปัจจุบัน

รหัสนี้ออกแบบมาเพื่อสร้างด้วย Visual Studio 2019 (16.11), Visual Studio 2022, clang สำหรับ Windows v12 หรือใหม่กว่า หรือ MinGW 12.2 จำเป็นต้องใช้ Windows 10 พฤษภาคม 2020 Update SDK (19041) หรือใหม่กว่าสำหรับ Visual Studio นอกจากนี้ยังสามารถสร้างสำหรับระบบย่อย Windows สำหรับ Linux โดยใช้ GCC 11 หรือใหม่กว่า

ส่วนประกอบเหล่านี้ได้รับการออกแบบมาให้ทำงานโดยไม่ต้องใช้เนื้อหาใดๆ จาก DirectX SDK รุ่นเก่า สำหรับรายละเอียด โปรดดูที่ DirectX SDK อยู่ที่ไหน

เค้าโครงไดเร็กทอรี

• DirectXTex

  • ประกอบด้วยไลบรารี DirectXTex ซึ่งรวมถึงตัวอ่านและตัวเขียน DDS ที่มีคุณลักษณะครบถ้วน รวมถึงการแปลงรูปแบบเดิม ตัวอ่านและตัวเขียน TGA ตัวอ่านและตัวเขียน HDR ตัวอ่านและตัวเขียนบิตแมปที่ใช้ WIC (BMP, JPEG, PNG, TIFF และ HD Photo) และ ฟังก์ชั่นการประมวลผลพื้นผิวต่างๆ มีจุดประสงค์เพื่อการใช้เครื่องมือเป็นหลัก

ไฟล์ส่วนหัวส่วนใหญ่ที่นี่มีไว้สำหรับการใช้งานไลบรารีภายในเท่านั้น ( BC.h , BCDirectCompute.h , DDS.h , DirectXTexP.h ฯลฯ ) เฉพาะ DirectXTex.h และ DirectXTex.inl เท่านั้นที่มีความหมายเป็นส่วนหัว 'สาธารณะ' สำหรับไลบรารี

• Auxiliary

  • มีไฟล์ต้นฉบับเพิ่มเติมสำหรับไลบรารี DirectXTex เช่นฟังก์ชันการโหลดอะแดปเตอร์โดยใช้ไลบรารี OpenEXR ส่วนขยายการปูกระเบื้องพื้นผิว Xbox เป็นต้น

• Common

  • มีส่วนหัวของแหล่งที่มาที่ใช้ร่วมกันซึ่งใช้โดยไลบรารีและเครื่องมือ DirectXTex

• Texconv

  • ตัวอย่าง DirectXTex นี้เป็นการใช้งานยูทิลิตีพื้นผิวบรรทัดคำสั่ง texconv ​​จาก DirectX SDK ที่ใช้ DirectXTex แทนที่จะเป็น D3DX

    รองรับอาร์กิวเมนต์เดียวกันกับยูทิลิตี้ DirectX SDK ดั้งเดิมของ Texture Conversion Tool Extended ( texconvex.exe ) ความแตกต่างหลักคืออาร์กิวเมนต์ -10 และ -11 ไม่สามารถใช้ได้ และชื่อตัวกรอง ( POINT , LINEAR , CUBIC , FANT หรือ BOX , TRIANGLE , *_DITHER , *_DITHER_DIFFUSION ) นอกจากนี้ยังรวมถึงการรองรับรูปแบบบิตแมป JPEG XR (HD Photo)

• Texassemble

  • ตัวอย่าง DirectXTex นี้เป็นโปรแกรมอรรถประโยชน์บรรทัดคำสั่งสำหรับสร้างคิวบ์แมป แมปวอลุ่ม หรืออาร์เรย์พื้นผิวจากชุดของไฟล์รูปภาพอินพุตแต่ละไฟล์

• Texdiag

  • ตัวอย่าง DirectXTex นี้เป็นโปรแกรมอรรถประโยชน์บรรทัดคำสั่งสำหรับการวิเคราะห์เนื้อหารูปภาพ โดยมีวัตถุประสงค์หลักในการแก้ไขจุดบกพร่อง

• DDSView

  • ตัวอย่าง DirectXTex นี้เป็นโปรแกรมดูที่ใช้ Direct3D 11 อย่างง่ายสำหรับไฟล์ DDS สำหรับพื้นผิวอาเรย์หรือแผนผังโวลุ่ม ปุ่มแป้นพิมพ์ "<" และ ">" จะแสดงรูปภาพต่างๆ ที่มีอยู่ใน DDS ปุ่ม "1" ถึง "0" ยังสามารถใช้เพื่อข้ามไปยังดัชนีรูปภาพที่ต้องการได้

• DDSTextureLoader

  • ประกอบด้วยเวอร์ชันที่ได้รับการปรับปรุงประสิทธิภาพของโค้ดการโหลดพื้นผิว DDSWithoutD3DX11 ตัวอย่าง DirectX SDK ดั้งเดิมสำหรับตัวโหลด DDS รันไทม์น้ำหนักเบาแบบธรรมดา มีเวอร์ชันสำหรับ Direct3D 9, Direct3D 11 และ Direct3D 12 ซึ่งไม่มีการแปลงข้อมูลพิกเซลรันไทม์ เหมาะอย่างยิ่งสำหรับการใช้งานรันไทม์ และรองรับทรัพยากรพื้นผิว Direct3D อย่างเต็มรูปแบบ (1D, 2D, โวลุ่มแมป, คิวบ์แมป, ระดับมิปแมป, อาร์เรย์พื้นผิว, รูปแบบ BC ฯลฯ)

• ScreenGrab

  • ประกอบด้วยโมดูลการเขียนพื้นผิวสำหรับ Direct3D 9, Direct3D 11 และ Direct3D 12 ที่มีไว้สำหรับสร้างภาพหน้าจอเป็นหลัก รูปภาพถูกเขียนเป็น DDS หรือเป็นรูปแบบไฟล์รูปภาพโดยใช้ WIC

• WICTextureLoader

  • ประกอบด้วยตัวโหลดพื้นผิว 2D Direct3D 9, Direct3D 11 และ Direct3D 12 ที่ใช้ WIC เพื่อโหลดบิตแมป (BMP, JPEG, PNG, HD Photo หรือคอนเทนเนอร์ไฟล์อื่น ๆ ที่รองรับ WIC) ปรับขนาดหากจำเป็นตามระดับคุณสมบัติปัจจุบัน (หรือ ด้วยพารามิเตอร์ที่ชัดเจน) ให้แปลงรูปแบบเป็น DXGI_FORMAT หากจำเป็น จากนั้นสร้างพื้นผิว 2D โปรดทราบว่าสิ่งนี้ไม่รองรับพื้นผิว 1D, พื้นผิววอลุ่ม, คิวบ์แมป หรืออาร์เรย์พื้นผิว แนะนำให้ใช้ DDSTextureLoader สำหรับพื้นผิวที่ "เตรียมไว้ล่วงหน้า" โดยสมบูรณ์เพื่อประสิทธิภาพและคุณภาพของภาพสูงสุด แต่ตัวโหลดนี้มีประโยชน์สำหรับการสร้างพื้นผิว 2D อย่างง่ายจากไฟล์ภาพมาตรฐานในขณะรันไทม์

DDSTextureLoader11, ScreenGrab11 และ WICTextureLoader11 เป็นเวอร์ชัน 'สแตนด์อโลน' ของโมดูลเดียวกันที่มีให้ในชุดเครื่องมือ DirectX สำหรับ DX11

DDSTextureLoader12, ScreenGrab12 และ WICTextureLoader12 เป็นเวอร์ชัน 'สแตนด์อโลน' ของโมดูลเดียวกันที่มีให้ในชุดเครื่องมือ DirectX สำหรับ DX12

• build

  • มีไฟล์ YAML สำหรับไปป์ไลน์บิวด์พร้อมกับไฟล์บิวด์และสคริปต์เบ็ดเตล็ด

เอกสารประกอบ

เอกสารมีอยู่ในวิกิ GitHub

ประกาศ

เนื้อหาและซอร์สโค้ดทั้งหมดสำหรับแพ็คเกจนี้อยู่ภายใต้ข้อกำหนดของใบอนุญาต MIT

สำหรับ DirectXTex เวอร์ชันล่าสุด รายงานข้อผิดพลาด ฯลฯ โปรดเยี่ยมชมไซต์โครงการบน GitHub

บันทึกประจำรุ่น

สำหรับคำแนะนำด้านความปลอดภัย โปรดดูที่ GitHub

สำหรับประวัติการเปลี่ยนแปลงทั้งหมด โปรดดูที่ CHANGELOG.md

• ตั้งแต่การเปิดตัวเดือนกรกฎาคม 2022 เป็นต้นไป พารามิเตอร์ bool forceSRGB สำหรับฟังก์ชัน CreateTextureEx และ CreateShaderResourceViewEx จะเป็นพารามิเตอร์แฟล็ก enum bitmask ที่พิมพ์ CREATETEX_FLAGS แล้ว นี่อาจมีผลกระทบต่อ การเปลี่ยนแปลงที่สำคัญ กับโค้ดไคลเอ็นต์ แทนที่ true ด้วย CREATETEX_FORCE_SRGB และ false ด้วย CREATETEX_DEFAULT

• เริ่มตั้งแต่การเปิดตัวเดือนมิถุนายน 2020 ไลบรารีนี้ใช้แฟล็กบิตมาสก์ enum ที่พิมพ์ตามคำแนะนำของส่วน มาตรฐาน C++ 17.5.2.1.3 ประเภทบิตมาสก์ ซึ่งสอดคล้องกับการใช้มาโคร DEFINE_ENUM_FLAG_OPERATORS ของ Direct3D 12 สิ่งนี้อาจมีผลกระทบต่อ การเปลี่ยนแปลงที่สำคัญ ต่อรหัสลูกค้า:

  • คุณไม่สามารถส่งผ่าน 0 ตัวอักษรเป็นค่าสถานะของคุณได้ แต่คุณต้องใช้ค่าแจงนับดีฟอลต์ที่เหมาะสม: CP_FLAGS_NONE , DDS_FLAGS_NONE , WIC_FLAGS_NONE , TEX_FR_ROTATE0 , TEX_FILTER_DEFAULT , TEX_FILTER_DEFAULT , TEX_FILTER_DEFAULT , CNMAP_DEFAULT หรือ CNMAP_DEFAULT

  • ใช้ประเภท enum แทน DWORD หากสร้างค่าแฟล็กในเครื่องด้วยการดำเนินการบิตมาสก์ ตัวอย่างเช่น DDS_FLAGS flags = DDS_FLAGS_NONE; if (...) flags |= DDS_FLAGS_EXPAND_LUMINANCE;

  • ในกรณีที่บางแฟล็กทับซ้อนกัน คุณสามารถใช้ | เพื่อรวมประเภทที่เกี่ยวข้อง: โหมดตัวกรอง TEX_FILTER_FLAGS รวมกับ WIC_FLAGS , TEX_FILTER_FLAGS ธง sRGB รวมกับ TEX_PMALPHA_FLAGS หรือ TEX_COMPRESS_FLAGS ไม่มีการกำหนดตัวดำเนินการระดับบิตอื่น ๆ ตัวอย่างเช่น WIC_FLAGS wicFlags = WIC_FLAGS_NONE | TEX_FILTER_CUBIC;

• WICTextureLoader ไม่สามารถโหลดไฟล์ .TGA หรือ .HDR ได้ เว้นแต่ระบบจะติดตั้งตัวแปลงสัญญาณ WIC ของบริษัทอื่นไว้ คุณต้องใช้ไลบรารี DirectXTex สำหรับการรองรับรูปแบบไฟล์ TGA/HDR โดยไม่ต้องใช้ตัวแปลงสัญญาณ WIC ของ Add-on

• โปรเจ็กต์ UWP และโปรเจ็กต์เดสก์ท็อป Win10 classic มีการกำหนดค่าสำหรับแพลตฟอร์ม ARM64 การสร้างสิ่งเหล่านี้จำเป็นต้องติดตั้งชุดเครื่องมือ ARM64

• สำหรับการพัฒนา ARM64/AArch64 แนะนำให้ใช้คอมไพลเลอร์ VS 2022 เหนือชุดเครื่องมือ VS 2019 Windows SDK (26100 หรือใหม่กว่า) เข้ากันไม่ได้กับ VS 2019 สำหรับ Win32 บนการพัฒนา ARM64 โปรดทราบว่าแพลตฟอร์ม ARM32/AArch32 เลิกใช้แล้ว

• เมื่อใช้ clang/LLVM สำหรับแพลตฟอร์ม ARM64/AArch64 จำเป็นต้องใช้ Windows 11 SDK (22000) หรือใหม่กว่า

• สคริปต์ CompileShaders.cmd ต้องมีการลงท้ายบรรทัดแบบ Windows (CRLF) หากเปลี่ยนเป็นการสิ้นสุดบรรทัดแบบ Linux (LF) ก็อาจไม่สามารถสร้างเชเดอร์ที่จำเป็นทั้งหมดได้

• ในการเปิดตัวเดือนตุลาคม 2024 เครื่องมือบรรทัดคำสั่งยังรองรับตัวเลือกแบบยาวแบบ GNU โดยใช้ -- สวิตช์ที่มีอยู่ทั้งหมดยังคงทำงานต่อไป แต่ตัวเลือก - บางส่วนเลิกใช้แล้วตามตารางนี้:

ประกอบเท็กซัส		เท็กซ์คอนวี		เท็กซ์เดียก
-โทนแมป	--tonemap	-แบดเทล	--หางไม่ดี	-แบดเทล	--หางไม่ดี
-บีจีคัลเลอร์	--gif-bg-สี	-fixbc4x4	--แก้ไข-bc-4x4	-ไม่สนใจ	--ละเว้น-mips
-swizzle	--สวิซซ์	-ไม่สนใจ	--ละเว้น-mips	-อนุญาต	--อนุญาต
-สตริปมิปส์	--แถบ-mips	-อินเวอร์เตอร์	--กลับด้าน-y	-เป้าหมายx	--เป้าหมาย-x
		-ให้ความคุ้มครอง	--เก็บความคุ้มครอง
		-อนุญาต	--อนุญาต
		-สร้างใหม่	--สร้างใหม่-z
		-rotatecolor	--หมุนสี
		-singleproc	--single-proc
		-swizzle	--สวิซซ์
		-tgazeroalpha	--tga-ศูนย์-อัลฟา
		-เวลา	--ระยะเวลา
		-โทนแมป	--tonemap
		-ไม่มีการสูญเสีย	--wic-สูญเสีย
		-wicmulti	--wic-มัลติเฟรม
		-x2อคติ	--x2-อคติ

สนับสนุน

หากมีคำถาม ให้ลองใช้ Stack Overflow กับแท็ก directxtk หรือ DirectX Discord Server ในช่อง dx12-developers หรือ dx9-dx11-developers

สำหรับรายงานข้อผิดพลาดและการร้องขอคุณสมบัติ โปรดใช้ปัญหา GitHub สำหรับโปรเจ็กต์นี้

มีส่วนร่วม

โครงการนี้ยินดีรับการสนับสนุนและข้อเสนอแนะ การบริจาคส่วนใหญ่กำหนดให้คุณต้องยอมรับข้อตกลงใบอนุญาตช่างภาพ (CLA) โดยประกาศว่าคุณมีสิทธิ์ที่จะให้สิทธิ์แก่เราในการใช้การบริจาคของคุณจริงๆ สำหรับรายละเอียด โปรดไปที่ https://cla.opensource.microsoft.com

เมื่อคุณส่งคำขอดึง บอท CLA จะกำหนดโดยอัตโนมัติว่าคุณจำเป็นต้องจัดเตรียม CLA และตกแต่ง PR อย่างเหมาะสมหรือไม่ (เช่น การตรวจสอบสถานะ ความคิดเห็น) เพียงทำตามคำแนะนำที่ได้รับจากบอท คุณจะต้องทำสิ่งนี้เพียงครั้งเดียวกับ repos ทั้งหมดโดยใช้ CLA ของเรา

ควรส่งการทดสอบคุณสมบัติใหม่เป็นการประชาสัมพันธ์ไปยังพื้นที่เก็บข้อมูลชุดทดสอบ

หลักจรรยาบรรณ

โครงการนี้ได้นำหลักจรรยาบรรณของ Microsoft Open Source มาใช้ สำหรับข้อมูลเพิ่มเติม โปรดดูคำถามที่พบบ่อยเกี่ยวกับจรรยาบรรณหรือติดต่อ [email protected] หากมีคำถามหรือความคิดเห็นเพิ่มเติม

เครื่องหมายการค้า

โครงการนี้อาจมีเครื่องหมายการค้าหรือโลโก้สำหรับโครงการ ผลิตภัณฑ์ หรือบริการ การใช้เครื่องหมายการค้าหรือโลโก้ของ Microsoft โดยได้รับอนุญาตนั้นอยู่ภายใต้และต้องปฏิบัติตามแนวทางเครื่องหมายการค้าและแบรนด์ของ Microsoft การใช้เครื่องหมายการค้าหรือโลโก้ของ Microsoft ในเวอร์ชันแก้ไขของโครงการนี้จะต้องไม่ทำให้เกิดความสับสนหรือบ่งบอกถึงการสนับสนุนของ Microsoft การใช้เครื่องหมายการค้าหรือโลโก้ของบุคคลที่สามจะต้องเป็นไปตามนโยบายของบุคคลที่สามเหล่านั้น

เครดิต

ไลบรารี DirectXTex เป็นผลงานของ Chuck Walbourn โดยได้รับการสนับสนุนจาก Matt Lee, Xin Huang, Craig Peeper และวิศวกร Microsoft คนอื่นๆ อีกจำนวนมากที่พัฒนาไลบรารียูทิลิตี้ D3DX ในช่วงหลายปีที่ผ่านมา

ขอขอบคุณ Paul Penson สำหรับความช่วยเหลือในการใช้งาน MemoryStreamOnBlob

ขอขอบคุณ Andrew Farrier และ Scott Matloff สำหรับความช่วยเหลืออย่างต่อเนื่องในการตรวจสอบโค้ด

ขอขอบคุณ Park DongHa สำหรับการสนับสนุนฟังก์ชันเสริม JPEG/PNG