From 4cc51d3178b8e5063f71c304d33b87e305847e73 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lukas=20Br=C3=BCbach?= Date: Wed, 2 Sep 2026 20:41:58 +0200 Subject: [PATCH] [Doxygen] Correct card-picture docs per review --- .../loading_card_pictures.md | 21 ++++++++------ .../card_pictures/custom_card_pictures.md | 29 +++++++++++-------- .../troubleshooting/fixing_card_pictures.md | 3 +- 3 files changed, 31 insertions(+), 22 deletions(-) diff --git a/doc/doxygen/extra-pages/developer_documentation/loading_card_pictures.md b/doc/doxygen/extra-pages/developer_documentation/loading_card_pictures.md index 46c1f454b..d23f6fc7c 100644 --- a/doc/doxygen/extra-pages/developer_documentation/loading_card_pictures.md +++ b/doc/doxygen/extra-pages/developer_documentation/loading_card_pictures.md @@ -74,7 +74,7 @@ redirects and applies them without an extra network round trip. The redirect cache is a hash map from original URL to redirect URL plus timestamp. It is persisted to a `cache.ini` file (Qt's INI format, under the `redirects` array) inside the redirect cache directory -(`SettingsCache::getRedirectCachePath()`, i.e. `/redirects/`). The cache is loaded when the worker +(`SettingsCache::instance().paths().getRedirectCachePath()`, i.e. `/redirects/`). The cache is loaded when the worker starts, pruned of entries older than the configured TTL, and written back to disk when the application quits. Entries are added whenever a network reply reports a redirection (see below) and are consulted before any request is @@ -102,8 +102,8 @@ CardPictureLoaderLocal searches two locations: - The **CUSTOM folder** (`/CUSTOM/`). Every file in it is indexed recursively by its base name (both `baseName` and `completeBaseName`, so a file named `ExampleCard.jpg` is indexed as `ExampleCard`). The index is rebuilt - every 10 seconds and whenever the pictures directory changes, so new files are picked up without restarting the - client. + every 10 seconds, so new files are picked up without restarting the + client (changing the configured pictures directory only reassigns the search paths; the next timer tick rebuilds the index). - The **set-named subfolders** of the pictures directory: `//` and `/downloadedPics//`. @@ -117,13 +117,13 @@ corrected name `Example Card`, set code `EXM` and collector number `43`. \attention The file-name variants use the *corrected* card name, so split cards are stored under their joined name: the "Example // Card" card is matched by a file named `ExampleCard.*`. -The naming schemes are duplicated in the user-facing page @subpage custom_card_pictures, which also documents how to +The naming schemes are duplicated in the user-facing page @ref custom_card_pictures, which also documents how to set up a custom card database that provides pictures via the CUSTOM folder and the `picurl` printing property. When the filesystem cache method is selected on the "Storage" settings page, downloaded images are additionally written into `/downloadedPics/` using the configured export naming scheme (as `.png` files). Existing files are never overwritten, so a provider outage can permanently leave a wrong image in that folder until it is deleted -manually - the user-facing troubleshooting guide @subpage fixing_card_pictures covers how to do this. +manually - the user-facing troubleshooting guide @ref fixing_card_pictures covers how to do this. # URL Generation and Resolution @@ -131,7 +131,8 @@ When no local image is available and downloading is enabled, the network loader candidate URLs. This list is managed by CardPictureToLoad and is built in two steps. First, CardPictureToLoad::extractSetsSorted() collects all sets the card has printings in and sorts them by set -priority. Unless the user disabled per-printing art ("Override all card art with personal preference"), the set that +priority. Unless the user disabled per-printing art ("Override all card art with personal set preference (Pre-ProviderID +change behavior)"), the set that matches the requested printing's provider ID is moved to the front, so the exact printing is always attempted first. For each set, CardPictureToLoad::populateSetUrls() builds an ordered URL list: @@ -164,7 +165,9 @@ The `!set:...!` and `!prop:...!` placeholders also support two modifiers: Substituted values are percent-encoded. If a template asks for a property the card or printing does not have (or one of the modifiers invalidates it), the template yields no URL and is skipped; the next template is tried instead. -\attention Custom URLs must start with `http://` or `https://` to be accepted. +\attention Custom URLs should start with `http://` or `https://`. The scheme is not validated before the URL is handed +to QNetworkAccessManager, so a template without an absolute scheme may silently fail to download; prefer HTTPS where the +provider allows it. The resolution order is: for the current set, try each URL in the list; when all URLs for a set are exhausted, move to the next set; when every set is exhausted, the load fails. A failed load is reported through the NULL-pixmap mechanism @@ -180,9 +183,9 @@ Several mechanisms influence the resolution process: redirect cache as described in the Redirect Cache section above. - **Blacklisted images.** Gatherer returns the card back image for cards it does not know. A few known MD5 hashes of that image are blacklisted, so such a "successful" download is treated as not found instead of being shown. -- **WebP.** Images detected as WebP (RIFF/WEBP header) are decoded through QMovie before being handed to QImageReader. +- **WebP.** Images detected as WebP (RIFF/WEBP header) are decoded through QMovie instead of QImageReader. - **Downloads disabled.** When "Download card pictures on the fly" is disabled and the network cache method is active, requests use Qt's `AlwaysCache` policy so that only previously cached images are served. A user-facing reference for writing download URL templates, including more worked examples, is available at -@subpage custom_card_pictures. \ No newline at end of file +@ref custom_card_pictures. diff --git a/doc/doxygen/extra-pages/user_documentation/card_pictures/custom_card_pictures.md b/doc/doxygen/extra-pages/user_documentation/card_pictures/custom_card_pictures.md index fcf298fe8..9b354fbf6 100644 --- a/doc/doxygen/extra-pages/user_documentation/card_pictures/custom_card_pictures.md +++ b/doc/doxygen/extra-pages/user_documentation/card_pictures/custom_card_pictures.md @@ -15,23 +15,26 @@ match a file there. - The folder is `/CUSTOM/`. The pictures directory is configured on the 'General' settings tab, under 'Directories' → 'Pictures directory'. -- Accepted formats are PNG, JPG and JPEG. +- Any image format Qt can decode is accepted (PNG, JPG/JPEG, WebP, GIF, BMP, ...); the file extension is not filtered, + so even an extension-less file is picked up if the decoder recognizes its content. - Files are indexed by their name, so you can organize them into subfolders freely. - New or changed files are picked up automatically within a few seconds — no client restart is required. The file name must match the card using one of the naming schemes below. Both `_` and `-` are accepted as separators, and the file extension is ignored when matching: -| Scheme | Example file name | -|-------------------------------|--------------------------------------------------------| -| Card Name | `Example Card.png` | -| Card Name + Set | `Example Card_DDL.png` | -| Card Name + Set + Collector | `Example Card_DDL_43.png` | -| Set + Collector + Card Name | `DDL_43_Example Card.png` | -| Card Name + Provider ID | `Example Card_0b23cdc8-d413-4fb1-8470-474221b10fe2.png` | +| Scheme | Example file name | +| --------------------------- | ------------------------------------------------------- | +| Card Name | `Example Card.png` | +| Card Name + Set | `Example Card_DDL.png` | +| Card Name + Set + Collector | `Example Card_DDL_43.png` | +| Set + Collector + Card Name | `DDL_43_Example Card.png` | +| Card Name + Provider ID | `Example Card_0b23cdc8-d413-4fb1-8470-474221b10fe2.png` | -The name used for matching is the *corrected* card name. In practice this means punctuation is stripped, so the -"Example // Card" card is matched by a file named `ExampleCard.png`, not `Example // Card.png`. +The name used for matching is the *corrected* card name. Correction removes the split-card separator ` // ` and the +characters reserved in Windows file names (`* < > : " \ ?` and control characters), and turns `/` into a space, so the +"Example // Card" card is matched by a file named `ExampleCard.png`, not `Example // Card.png`. Most other punctuation +(commas, apostrophes, `!`, ...) is left untouched. \attention A file in the CUSTOM folder always wins over downloaded pictures, even if it is the wrong image. Delete the file if you want to see the downloaded artwork again. @@ -52,7 +55,8 @@ tag can carry a `picurl` attribute containing a full URL for that printing's pic Cockatrice tries this URL **before** the configured download URL templates, so it is the most direct way to provide custom artwork for a specific printing. -- The URL must start with `http://` or `https://`. +- The URL should start with `http://` or `https://`; the scheme is not validated, so make sure it is absolute or the + download may silently fail. - When you change a `picurl` for a card whose picture was already downloaded and cached, delete the stored images (Storage tab → 'Delete Saved Images' / 'Delete Cached Images') so Cockatrice fetches the new URL. @@ -86,7 +90,8 @@ The `!set:...!` and `!prop:...!` reference points support two modifiers: Substituted values are URL-encoded. A template that asks for a property the card or printing does not have is skipped, and the next template in the list is tried instead. -\attention Custom URLs must start with `http://` or `https://` to be accepted. +\attention Custom URLs should start with `http://` or `https://`. As with `picurl`, the scheme is not validated before +the URL is handed to QNetworkAccessManager, so use an absolute URL or the download may silently fail. Some working examples: diff --git a/doc/doxygen/extra-pages/user_documentation/troubleshooting/fixing_card_pictures.md b/doc/doxygen/extra-pages/user_documentation/troubleshooting/fixing_card_pictures.md index 066c71786..abdf4a291 100644 --- a/doc/doxygen/extra-pages/user_documentation/troubleshooting/fixing_card_pictures.md +++ b/doc/doxygen/extra-pages/user_documentation/troubleshooting/fixing_card_pictures.md @@ -43,7 +43,8 @@ Cockatrice checks the following locations, in order: - `//` - `/downloadedPics//` -The following import naming schemes are recognized (using both `_` and `-` as separators): +The following import naming schemes are recognized (using both `_` and `-` as separators). The canonical table with +concrete example file names is on @ref custom_card_pictures: | Scheme | Pattern | | --------------------------- | -------------------------- |