Improve "The Timing of LYC STAT Handlers" #42

ISSOtm · 2022-01-08T20:44:53Z

Largely editing work, but also some content changes.

[EDIT] The article as of 2022-02-28 is now online

rondnelson99 · 2022-01-09T00:32:59Z

Thanks so much for these changes. They definitely add a lot of polish to the document. The only change I'm a little unsure about is the one regarding hardware.inc constants. I added the STATB_xxxx constants to hardware.inc back in august, so they are present as long as the reader is using a recent version. I personally prefer using these constants with set and res so that it is more clear that I'm setting and resetting bits. I find it especially confusing when people invert the flag constants when resetting bits with and. Most importantly, I also use those flags when reading STAT later in the tutorial using bit n, [hl]. Since and and or aren't usable this way, the STATB_xxxx constants need to be used anyways, so I was inclined to use them throughout the whole document for consistency. I get why you'd want to use the older constants that everyone is more familiar with though.

ISSOtm · 2022-01-09T00:37:52Z

Yeah, STATB_ constants are present, but LCDCB_ aren't.

rondnelson99 · 2022-01-09T00:46:45Z

Right, yeah, my bad. Come to think of it, I wonder why I didn't add those when I added all those other bit numbers to hardware.inc. I probably just missed them.

avivace

Wow, this looks impressive (and definitely not overkilled :P). Congrats on the custom Vue component @ISSOtm 🥳

Some stuff I'd like to do:

propose a new palette (and maybe make it consistent also with similar graphical assets on Pan Docs)
set the "Scanline cycle" numbers to monospaced (or fixed-width sans serif)
Replace the first timing image from Pan Docs with its SVG version, using Pan Docs upstream location so the two remain in sync
see if there's a workaround for an artifact I still see at some zoom levels (see the purple 1-pixel line at the bottom):

A part from that it looks like an appreciated and already merge-able upgrade.

website/.vuepress/config.js

website/guides/lyc_timing.md

ISSOtm · 2022-01-10T23:47:19Z

Wow, this looks impressive (and definitely not overkilled :P).

Thank you! And hey, aiming too high is how we got a lot of our resources where they are, isn't it? 😜

Congrats on the custom Vue component @ISSOtm 🥳

It took some effort form both of us, but I'm mostly glad that what I bodged up didn't make you want to throw up too hard 😅

Some stuff I'd like to do:

propose a new palette (and maybe make it consistent also with similar graphical assets on Pan Docs)

That I'll leave to you, both so that I can focus on improving the content, and because you're much better at this task than I. (All I could do to pick colors for the Pan Docs SVGs was use a colorblind-friendly palette as-is...)

set the "Scanline cycle" numbers to monospaced (or fixed-width sans serif)

Should be a simple fix indeed. Note that we currently are using what seems to be Vuepress' default font stack and not Inter.

Replace the first timing image from Pan Docs with its SVG version, using Pan Docs upstream location so the two remain in sync

I don't think it would be possible to pull the image directly from Pan Docs. It should however be possible to e.g. have CI warn when deploying if the upstream image was updated, which should be the next best thing.

I'll look into making it themed as well, though as you suggested this is likely to require a special plugin since <style> inside SVGs trigger a failsafe (?) in Vuepress, and it'd be nice to have the "image" partial be external anyway.

A part from that it looks like an appreciated and already merge-able upgrade.

Well, the content still needs some changes (mostly editorial, like polishing the article's pacing a bit, showcasing STAT VRAM accesses with a block of code and a more detailed explanation) as well as corrections (some timings were incorrect, and thus some timelines are no longer consistent with the text). So I don't think it should be merged as-is—hence the draft status, actually.

avivace · 2022-01-29T22:35:50Z

website/guides/lyc_timing.md

+                    class: className,
+                    condensed: slotProps.op === 'condensed',
+                };
+                let contents = props.condensed ? h('b', {}, '(...)') : instrName && h('code', {}, instrName);


I think a simple ... fits better, why is that in bold and between parenthesis?

Because otherwise it was too easy to miss

avivace · 2022-01-29T22:40:33Z

I'm trying to work on a updated palette. Main issue now is how bright STAT read

and call some func are

Also, some of the timeline graphs reach eight different colors.. That's definitely too much and confusing but I still didn't manage to find a better solution..

ISSOtm · 2022-01-29T23:34:33Z

Agree about the yellow, but I'm having a hard time getting good-looking colors with both the light and dark schemes.

Are that many colors a problem? They are separated into two columns, after all?

Use single quotes or code blocks where appropriate instead

Avoids polluting the ToC

To be consistent with Pan Docs' style guide https://github.com/gbdev/pandocs/wiki/Document-Style#6-horizontal-blanking-interval-vertical-blanking-interval

8 is typically too much in <pre> blocks on the Web

Should improve readability

Should help ground the introduction

Those are not part of their names, and rather indicate addresses

They should be somewhat more readable, though there is still romm for improvement

Not just the one it starts on, but all that it goes through

This will allow the next change to pull some of the lines programmatically

This will propagate modifications made to one to the other as well. Additionally, this uncovered a couple of slip-ups, which were corrected.

And make it follow the theme as well, of course!

Shorter and independent of the `.temp` folder location

Use a set of colorblind-friendly colors Do not color IO instructions specially besides their important cycle Make the specific IO cycle pop out more Only label that specific cycle in the legend

Add "..." to imply their purpose more strongly, and make that bold to make it stand out a bit more against the background

That's a much more accurate label

It would *remove* everything before the semicolon, which is the opposite of what we want

Makes them easier to read, since entries are introduced in the same order that they are in the timeline being labelled

avivace · 2022-03-23T09:56:11Z

Thanks @ISSOtm I'll start merging it in the current state and we can proceed from here with another PR

avivace approved these changes Jan 10, 2022

View reviewed changes

ISSOtm commented Jan 10, 2022

View reviewed changes

website/.vuepress/config.js Outdated Show resolved Hide resolved

ISSOtm commented Jan 10, 2022

View reviewed changes

website/guides/lyc_timing.md Outdated Show resolved Hide resolved

avivace requested changes Jan 29, 2022

View reviewed changes

ISSOtm added 20 commits January 31, 2022 22:53

Remove single quotation marks

108a7ad

Use single quotes or code blocks where appropriate instead

Use bold text instead of anchor in Pan Docs quote

42da6a1

Avoids polluting the ToC

Fix whitespace formatting

c3a6052

Rename "Hblank" to "HBlank"

7172b57

To be consistent with Pan Docs' style guide https://github.com/gbdev/pandocs/wiki/Document-Style#6-horizontal-blanking-interval-vertical-blanking-interval

Set indentation to 4 spaces

e8c443e

8 is typically too much in <pre> blocks on the Web

Use constants present in hardware.inc

cb49b9a

Make code style consistent

2503e3f

Should improve readability

Add DeadCScroll GIF to showcase a raster FX example

1468eec

Should help ground the introduction

Remove "r" prefix from reg names in prose

94ab723

Those are not part of their names, and rather indicate addresses

Use monospaced text for all reg names and instructions in prose

f3765b6

Update DeadCScroll to point to new gbdev.io version

7b617cf

Convert scanline timing diagrams to <table>

fe7e855

They should be somewhat more readable, though there is still romm for improvement

Set "..." cells background to represent the different modes

64e1a5f

Not just the one it starts on, but all that it goes through

Correct io-3cycle "gradient" to fix off-by-one pixel

01c1c48

Hoist code blocks to separate files

a861158

This will allow the next change to pull some of the lines programmatically

Make all "timelines" load ASM lines

b7277db

This will propagate modifications made to one to the other as well. Additionally, this uncovered a couple of slip-ups, which were corrected.

Use a SVG for the PPU timing diagram

53f7c8e

And make it follow the theme as well, of course!

Make ASM import paths use alias

daafb8c

Shorter and independent of the `.temp` folder location

Improve timelines color palette

989510f

Use a set of colorblind-friendly colors Do not color IO instructions specially besides their important cycle Make the specific IO cycle pop out more Only label that specific cycle in the legend

Mark "condensed" rows more explicitly as such

1b99f04

Add "..." to imply their purpose more strongly, and make that bold to make it stand out a bit more against the background

ISSOtm added 7 commits January 31, 2022 22:53

Rename "skip" to "condensed"

86308db

That's a much more accurate label

Document a non-obvious purpose of the PPU mode color vars

3934d30

Error out when referencing an unregistered ASM file

e30b3ce

Report ASM file location when a relevant error occurs

eb9e1a9

Fix removal of comments in ASM files

8e96746

It would *remove* everything before the semicolon, which is the opposite of what we want

Sort timeline legends chronologically

a8981d5

Makes them easier to read, since entries are introduced in the same order that they are in the timeline being labelled

[WIP] Overhaul article contents

622197b

avivace marked this pull request as ready for review March 23, 2022 09:54

avivace merged commit 7b0b5f8 into gbdev:dev Mar 23, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve "The Timing of LYC STAT Handlers" #42

Improve "The Timing of LYC STAT Handlers" #42

ISSOtm commented Jan 8, 2022 •

edited

Loading

rondnelson99 commented Jan 9, 2022 •

edited

Loading

ISSOtm commented Jan 9, 2022

rondnelson99 commented Jan 9, 2022

avivace left a comment •

edited

Loading

ISSOtm commented Jan 10, 2022

avivace Jan 29, 2022

ISSOtm Jan 29, 2022

avivace commented Jan 29, 2022

ISSOtm commented Jan 29, 2022

avivace commented Mar 23, 2022

Improve "The Timing of LYC STAT Handlers" #42

Improve "The Timing of LYC STAT Handlers" #42

Conversation

ISSOtm commented Jan 8, 2022 • edited Loading

rondnelson99 commented Jan 9, 2022 • edited Loading

ISSOtm commented Jan 9, 2022

rondnelson99 commented Jan 9, 2022

avivace left a comment • edited Loading

Choose a reason for hiding this comment

ISSOtm commented Jan 10, 2022

avivace Jan 29, 2022

Choose a reason for hiding this comment

ISSOtm Jan 29, 2022

Choose a reason for hiding this comment

avivace commented Jan 29, 2022

ISSOtm commented Jan 29, 2022

avivace commented Mar 23, 2022

ISSOtm commented Jan 8, 2022 •

edited

Loading

rondnelson99 commented Jan 9, 2022 •

edited

Loading

avivace left a comment •

edited

Loading