From 8754dbe92a4a9d9bc4ae3fb3fa6bd507cf5ee482 Mon Sep 17 00:00:00 2001 From: Mark Callow <2244683+MarkCallow@users.noreply.github.com> Date: Sat, 1 Feb 2025 12:11:45 +0900 Subject: [PATCH] Move CI to GitHub Actions (#223) * Implement GitHub Pages site to show files generated from latest commit to main. * Fix docrev and revision history for upcoming release. * Update README. * Delete outdated TODO. --- .github/workflows/build.yml | 55 +++++++++++++++++------------------ .travis.yml | 35 ---------------------- Makefile | 56 ++++++++++++++++++++++++++++------- README.md | 58 +++++++++++++------------------------ TODO.md | 18 ------------ ghpages-index.adoc | 28 ++++++++++++++++++ ktxspec.adoc | 8 +++-- switch_test/Makefile | 32 +++++++++++++------- 8 files changed, 147 insertions(+), 143 deletions(-) delete mode 100644 .travis.yml delete mode 100644 TODO.md create mode 100644 ghpages-index.adoc diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 61c7624..1ea9889 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -24,46 +24,43 @@ on: jobs: build-specs: - name: Build KTX and KTX Fragments specifications + name: Build KTX File Format and KTX Fragment URI specifications runs-on: ubuntu-latest - env: - GIT_LFS_SKIP_SMUDGE: 1 - WERROR: ON - steps: - uses: actions/checkout@v4 -# - uses: ruby/setup-ruby@v1 -# with: -# ruby-version: 2.7 + - name: Install Asciidoctor + run: sudo apt-get install -y asciidoctor + + - name: Build specs + run: make ghpages - - uses: reitzig/actions-asciidoctor@v2.0.2 + - name: Upload generated files for GitHub Pages + id: deployment + uses: actions/upload-pages-artifact@v3 with: - version: 2.0.18 - -# - name: Force fetch provoking tag's annotation. -# # Work around https://github.com/actions/checkout/issues/290. -# if: github.ref_type == 'tag' -# run: git fetch -f origin ${{ github.ref }}:${{ github.ref }} - - - run: make - -# - name: Upload To Pages -# uses: softprops/action-gh-release@v1 -# if: github.event_name == 'push' && github.ref_type == 'tag' -# with: -# draft: true -# prerelease: true -# files: KTX-Software-${{env.KTX_VERSION}}-Android.zip* -# env: -# GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - - # Deploy job + path: out/ghpages/ + + generate-switches: + name: Generate and test compile format conversion switches. + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + + - name: Generate switches + run: make switches + + - name: Test compile switches + run: make testswitches + deploy: name: Deploy to GitHub Pages # Add a dependency to the build job needs: build-specs + # Only deploy when building `main`. + if: github.ref == 'refs/heads/main' # Grant GITHUB_TOKEN the permissions required to make a Pages deployment permissions: diff --git a/.travis.yml b/.travis.yml deleted file mode 100644 index 3c5b4e2..0000000 --- a/.travis.yml +++ /dev/null @@ -1,35 +0,0 @@ -# CI build script for Travis. -# See https://docs.travis-ci.com/user/multi-os/ for more info. - -os: osx -osx_image: xcode14.2 - -language: ruby - -branches: - exclude: action-develop -# only: -# - master -# # Enable building of tags. -# - /2.0.*/ - -install: sudo gem install asciidoctor - -before_script: - - echo -e "machine github.com\n login $GITHUB_TOKEN" >> ~/.netrc - - ./install-gitconfig.sh - - rm TODO.md - - git checkout TODO.md - -script: - - make - # Test switch generator and generated switches. - - pushd switch_test; make; popd - -deploy: - provider: pages - edge: true - github-token: $GITHUB_TOKEN # Set in the settings page of your repository, as a secure variable - local-dir: out - on: - tags: true diff --git a/Makefile b/Makefile index 54f7e9a..0ae210d 100644 --- a/Makefile +++ b/Makefile @@ -1,14 +1,17 @@ # Copyright (c) 2014-2017 The Khronos Group Inc. # Copyright notice at https://www.khronos.org/registry/speccopyright.html -# Use docs for compatibility with GitHub pages. out=out -ktxspec=$(out)/ktxspec.v2 -ktxfrag=$(out)/ktx-frag +out.specs = $(out)/specs +out.switches = $(out)/switches +out.ghpages = ${out}/ghpages + +ktxspec = $(out.specs)/ktxspec.v2 +ktxfrag = $(out.specs)/ktx-frag all: $(ktxspec).html $(ktxfrag).html #$(ktxspec).pdf -regdoc: $(out)/ktx-media-registration.txt +regdoc: $(out.specs)/ktx-media-registration.txt ktx_inlined_images := icons/ktx_favicon.ico \ images/cubemap_coord_system.svg \ @@ -25,7 +28,6 @@ ktx_sources := ktxspec.adoc \ ktx-media-registration.adoc \ license.adoc \ khronos.css \ - $(out) \ $(ktx_inlined_images) \ docinfo.html @@ -33,14 +35,30 @@ frag_inlined_images := icons/ktx_favicon.ico frag_sources := ktx-frag.adoc \ khronos.css \ - $(out) \ $(frag_inlined_images) \ docinfo.html -$(ktxspec).html: $(ktx_sources) +ghpages.index := $(out.ghpages)/index.html +ghpages.ktxspec := $(out.ghpages)/ktxspec.v2.html +ghpages.ktxfrag := $(out.ghpages)/ktx-frag.html + +# For GitHub CI to build GitHub Pages site. +ghpages: $(ghpages.index) $(ghpages.ktxspec) $(ghpages.ktxfrag) images/khronos.svg images/ktx.svg + + +switches := vkFormat2dxgiFormat.inl \ + vkFormat2glInternalFormat.inl \ + vkFormat2mtlFormat.inl \ + vkFormat2glFormat.inl \ + vkFormat2glType.inl +switches := $(addprefix ${out.switches}/,${switches}) + +switches: $(switches) + +$(ktxspec).html: $(ktx_sources) | $(out.specs) asciidoctor --trace -v --failure-level INFO -r ./inline-images.rb -r ./formats-include.rb -D $(dir $@) -o $(notdir $@) $< -$(ktxfrag).html: $(frag_sources) +$(ktxfrag).html: $(frag_sources) | $(out.specs) asciidoctor --trace -v --failure-level INFO -r ./inline-images.rb -D $(dir $@) -o $(notdir $@) $< $(ktxspec).pdf: @@ -66,15 +84,33 @@ end endef # Creates pure-text version of media-registration for submission to IANA. -$(out)/ktx-media-registration.txt: ktx-media-registration.adoc $(out) +$(out.specs)/ktx-media-registration.txt: ktx-media-registration.adoc | $(out.specs) ruby -e '$(pure.rb)' $< >$@ +$(ghpages.index): ghpages-index.adoc + asciidoctor --trace -v --failure-level INFO -r ./inline-images.rb -D $(dir $@) -o $(notdir $@) $< + +${out.ghpages}/%.html: ${out.specs}/%.html + cp $< $@ + +# &: is the "grouping separator" added in GNU make 4.3 to tell Make that +# the command generates all listed targets. Earlier versionsa treat this +# the same as the : separator and will issue the command for each target. +$(switches) &: formats.json formats.schema.json generate_format_switches.rb | $(out.switches) + ./generate_format_switches.rb $(out.switches) + +testswitches: $(switches) + cd switch_test; $(MAKE) switches_dir=../$(out.switches) + $(out): mkdir -p $@ +$(out.specs) $(out.switches): | $(out) + mkdir -p $@ + clean: clobber: clean - rm -rf $(out) + rm -rf $(out.specs) $(out.switches) $(out.ghpages) $(out) # vim: ai noexpandtab tw=72 ts=4 sw=4 diff --git a/README.md b/README.md index b3a4447..ab5dfba 100644 --- a/README.md +++ b/README.md @@ -5,16 +5,20 @@ KTX is a file format that can be used for storing GPU-ready texture data (with cubemaps, mip levels, etc). Like DDS but with more features and more formal specification. It supports Basis Universal transcodable formats and supercompression which can yield JPEG-sized universal textures. glTF will use Basis Universal textures in KTX v2 containers. -Click to see the latest published versions of the [KTX File Format Specification](https://registry.khronos.org/KTX/specs/2.0/ktxspec.v2.html) +Click these links to see the latest published versions of the +[KTX File Format Specification](https://registry.khronos.org/KTX/specs/2.0/ktxspec.v2.html) or the [KTX Fragment URI Specification](https://registry.khronos.org/KTX/specs/2.0/ktx-frag.html) -from the Khronos KTX Registry (they look much better than the ersatz views provided by GitHub) or run +from the Khronos KTX Registry, visit the project's +[GitHub Pages](https://github.khronos.org/KTX-Specification/) to see formatted +versions of the latest commits to `main` (both options look much better than +the ersatz views provided by GitHub) or run -```.bash +```bash make ``` in a Unix-like environment with [AsciiDoctor](https://asciidoctor.org/docs/install-toolchain/) -installed to generate the publishable specs. They are the files `out/ktxspec.v2.html` and `out/ktx-frag.html`. +installed to generate the publishable specs. They are the files `out/specs/ktxspec.v2.html` and `out/specs/ktx-frag.html`. Everything needed is inlined. The canonical KTX spec. text is in the file `ktxspec.adoc`. The canonical fragment URI spec. text is in the file `ktx-frag.html`. @@ -29,38 +33,16 @@ To ensure correct mappings from Vulkan's `VkFormat` to other GPU APIs, this repo - [JSON database](formats.json) ([schema](formats.schema.json)) with mappings to OpenGL, Direct3D, and Metal enums. - [Switch-case generator](generate_format_switches.rb) that produces 5 files with simple C-like case-return statements. > **Usage:** `./generate_format_switches.rb []` -- [Compile test of the case statements](switch_test/vk2gl.c) that serves as an example of use. - -### $Date$ keyword expansion - -A few auxiliary files have `$Date$` keywords. If you care about having -the proper dates shown on files in your workspace, you **must** follow the -instructions below. - -$Date$ keywords are expanded via a smudge & clean filter. To install -the filter, issue the following commands in the root of your clone. - -On Unix (Linux, Mac OS X, etc.) platforms and Windows using Git for Windows' -Git Bash or Cygwin's bash terminal: - -```bash -./install-gitconfig.sh -rm TODO.md -git checkout TODO.md -``` - -On Windows with the Command Prompt (requires `git.exe` in a directory -on your %PATH%): - -```cmd -install-gitconfig.bat -del TODO.md -git checkout TODO.md -``` - -The first command adds an [include] of the repo's `.gitconfig` to the -local git config file `.git/config`, i.e. the one in your clone of the repo. -`.gitconfig` contains the config of the "dater" filter. The remaining -commands force a new checkout of the affected files to smudge them with the -date. These two are unnecessary if you plan to edit these files. +- [Compile test of the case statements](switch_test/vk2gl.c) that serves as an example of use. To try the compile test do + + ```bash + cd switch_test + make + ``` + or + + ```bash + make testswitches + ``` + diff --git a/TODO.md b/TODO.md deleted file mode 100644 index 036d737..0000000 --- a/TODO.md +++ /dev/null @@ -1,18 +0,0 @@ -KTX Format Specification TO DO List -=================================== - -$Date$ - -file format ------------ - -- [x] support swizzles -- [x] support max (smallest) to base (largest) ordering of mipmap levels to help when streaming -- [ ] support use Basis/Crunch on images -- [x] support use of zlib and ANS compression on images - -general -------- - -- [x] design icon for KTX files -- [ ] design icon for KTX2 files diff --git a/ghpages-index.adoc b/ghpages-index.adoc new file mode 100644 index 0000000..082fdf1 --- /dev/null +++ b/ghpages-index.adoc @@ -0,0 +1,28 @@ += KTX Specifications (Latest Committed Versions) +:author: Mark Callow +:author_org: Edgewise Consulting +:description: Main page for KTX GitHub pages site +//:docrev: 3 +//:ktxver: 2.0 +//:revnumber: {ktxver}.{docrev} +//:revdate: {docdate} +//:version-label: Version +:lang: en +:docinfo1: +:doctype: article +:encoding: utf-8 +:stylesheet: khronos.css +:imagesdir: images +:data-uri: + +:url-khr-reg: https://registry.khronos.org +:url-khr-ktx: {url-khr-reg}/KTX + +These generated documents reflect the latest commits to the main branch +of the specification source repo. For latest released (published) versions +see {url-khr-ktx}[the KTX Registry]. + +* link:ktxspec.v2.html[KTX v2.0 Specification] +* link:ktx-frag.html[KTX Fragment URI Specification] + + diff --git a/ktxspec.adoc b/ktxspec.adoc index fe70504..dc58d91 100644 --- a/ktxspec.adoc +++ b/ktxspec.adoc @@ -2,7 +2,7 @@ :author: Mark Callow :author_org: Edgewise Consulting :description: Specification of a container format for GPU textures. -:docrev: 3 +:docrev: 4 (draft) :ktxver: 2.0 :revnumber: {ktxver}.{docrev} :revdate: {docdate} @@ -2455,11 +2455,15 @@ include::appendices/vendor-metadata.adoc[] GL formats mapping. - Increase document width from 55em to 60em. -| {docrev} | {revdate} | - Fix `typeSize` for formats with +| 3 | 2024-02-20 | - Fix `typeSize` for formats with `_nPACKxx` suffix. - Prohibit YCbCr 2-plane 444 formats recently added to Vulkan. - Allow `A8B8G8R8*PACK32` formats. +| {docrev} | {revdate} | - Relax restrictions on + `colorPrimaries` values. + - Fix bit size of descriptorType in + dfdBlock. - Do not use "default" in describing the object coordinate systems commonly used with OpenGL and diff --git a/switch_test/Makefile b/switch_test/Makefile index 8a74c58..a9e1ed3 100644 --- a/switch_test/Makefile +++ b/switch_test/Makefile @@ -4,13 +4,24 @@ # SPDX-License-Identifier: Apache-2.0 depth := .. -inlines := vkFormat2glFormat.inl \ - vkFormat2glInternalFormat.inl \ - vkFormat2glType.inl -khrregistry := https://registry.khronos.org dest := build +switches_dir ?= $(dest) +switches := vkFormat2glFormat.inl \ + vkFormat2glInternalFormat.inl \ + vkFormat2glType.inl +switches := $(addprefix ${switches_dir}/,${switches}) + +# Make a switches dir relative to the directory $(depth) because that is where +# generate_format_switches must be run. +ifeq ($(switches_dir), $(dest)) + # Produces a full path name. $(dir ...) results ends in a'/' so $(notdir ...) + # would return an empty string. + generated_switches_dir := $(dir $(abspath $(lastword $(MAKEFILE_LIST))))$(dest) +else + generated_switches_dir := $(subst $(depth)/,,${switches_dir}) +endif -inlines := $(addprefix ${dest}/,${inlines}) +khrregistry := https://registry.khronos.org # This is to use the specially generated vulkan_core.h with the ASTC 3D # format enumerators. @@ -27,23 +38,22 @@ vkheaders := vulkan/vk_platform.h # vk_video/vulkan_video_codec_av1std.h \ # vk_video/vulkan_video_codec_av1std_decode.h vkheaders := $(addprefix ${dest}/,${vkheaders}) -mkfile_dir := $(dir $(abspath $(lastword $(MAKEFILE_LIST)))) default: test_compile -inlines: $(inlines) +switches: $(switches) headers: $(dest) $(addprefix ${dest}/,GL/glcorearb.h KHR/khrplatform.h vulkan/vulkan_core.h) test_compile: $(dest)/vk2gl.o -CFLAGS := -I $(dest) -Werror -c +CFLAGS := -I $(switches_dir) -I $(dest) -Werror -c -$(dest)/vk2gl.o: inlines headers +$(dest)/vk2gl.o: switches headers | $(dest) $(CC) $(CFLAGS) -o $@ vk2gl.c # &: is the "grouping separator" added in GNU make 4.3 to tell Make that # the command generates all listed targets. Earlier versionsa treat this # the same as the : separator and will issue the command for each target. -$(inlines) &: $(dest) $(depth)/formats.json $(depth)/generate_format_switches.rb - cd $(depth); ./generate_format_switches.rb $(mkfile_dir)/$(dest) +$(switches) &: $(depth)/formats.json $(depth)/formats.schema.json $(depth)/generate_format_switches.rb |$(dest) + cd $(depth); ./generate_format_switches.rb $(generated_switches_dir) $(dest)/GL/glcorearb.h: curl --create-dirs --output-dir $(dest)/GL -L -O $(khrregistry)/OpenGL/api/GL/glcorearb.h