Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Dev docs #2730

Merged
merged 10 commits into from
Apr 8, 2017
Merged

Dev docs #2730

merged 10 commits into from
Apr 8, 2017

Conversation

Frenzie
Copy link
Member

@Frenzie Frenzie commented Apr 6, 2017

doc/Events.md Outdated

Each event is an object that has two properties: `args` and `handler`. `handler` is the name of function that will be called on receive. `args` is a table that contains all the arguments needed to be passed to the event handler. When a widget receives a event, it will first check to see if `self[event.handler]` exists. If yes, the `self[event.handler]` function will be called and the return value of the handler will be returned to UIManager.

Notice that if you don't want the event propagate after consumed in your handler, your handler must return True. Otherwise, the event will be passed to other widgets' handlers until one of the handlers returns True.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

s/True/true. Or s/True/true.

doc/Hacking.md Outdated
logger.dbg("table a: ", a)
```

Anything printed by `logger.dbg` starts with a `#` sign.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is the behavior for the deprecated DEBUG function. New logger prints in the following format now:

04/06/17-21:44:53 DEBUG foo

doc/Hacking.md Outdated

## Bug hunting in kpv

A real example for hunting bug in KPV's cache system: https://github.com/koreader/kindlepdfviewer/pull/475
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

KPV! Is this still relevant to KOReader?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I barely even read it diagonally after making the link to point to the right repository, but it looked like the comments around koreader/kindlepdfviewer#475 (comment) might still be somewhat relevant to #2502. I'd never even heard of KOReader at the time (or kindlepdfviewer) and you added it to the wiki, so it's up to you. :-)

doc/Porting.md Outdated
## Output Module

KOReader uses framebuffer to control EInk devices, so the output module here is
[einkfb.c][einkfb-c]. You can find this file in koreader-base framework. The
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section is out of date now. einkfb has been ported to lua under base/ffi/framebuffer_einkfb.lua.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right, a couple of the links point to outdated locations. Is there anything substantial that's off?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about something like this? I removed the final two paragraphs and for the rest basically kept the text.


KOReader uses framebuffer to control EInk devices, so the output module here is
base/ffi/framebuffer_einkfb.lua.

Following are the framebuffers that framebuffer_einkfb.lua currently supports:

  • 4BPP inverted framebuffer
  • 16 scale 8BPP inverted framebuffer
  • 16 scale 8BPP framebuffer

For 4BPP framebuffer, it means every pixel is represented with 4 bits, so we
have 2 pixels in 1 byte. So the color depth is 16. The inverted part means all
the bits are flipped in the framebuffer. For example, two pixels [0x00, 0xf0]
will be stored as 0xff0f in framebuffer.

For 16 scale 8BPP framebuffer, it means each pixel is instead stored in 1 byte,
but the color depth is still 16 (4bits). Since 1 byte has 8 bits, so to fill
up the remaining space, the most significant 4 bits is a copy of the least
significant one. For example, pixel with grey scale 15 will be represented as
0xffff. If it's a inverted 16 scale 8BPP framebuffer, then all the bits are
flipped in the same way as 4BPP inverted framebuffer does.

If your device's framebuffer does not fit into any of the categories above,
then you need to add a new transformation function in framebuffer_einkfb.lua.

The framebuffer_einkfb.lua module works in following ways for non 4BPP framebuffers;

  • a shadow buffer is created and structured as 4BPP inverted framebuffer.
  • all updates on screen bitmap are temporally written into the shadow buffer.
  • each time we want to reflect the updated bitmap on screen, we translate
    the shadow buffer into a format that the real framebuffer understands and
    write into the mapped memory region. (varies on devices)
  • call ioctl system call to refresh EInk screen. (varies on devices)

KOReader will handle the 4BPP shadow buffer for you, all you need to do is to
teach framebuffer_einkfb.lua how to control the EInk screen and translate the 4BPP inverted
bitmap into the format that your framebuffer understands.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

looks good to me :)

@Frenzie
Copy link
Member Author

Frenzie commented Apr 8, 2017

That should about do it for a first pass. The wiki here has been purged of developer stuff so users should be less likely to be confused. There's still some stuff left in the base wiki: https://github.com/koreader/koreader-base/wiki

@houqp houqp merged commit e217b99 into koreader:master Apr 8, 2017
@Frenzie Frenzie deleted the dev-docs branch April 8, 2017 10:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants