{"action":"created","issue":{"url":"https://api.github.com/repos/ebassi/graphene/issues/43","labels_url":"https://api.github.com/repos/ebassi/graphene/issues/43/labels{/name}","comments_url":"https://api.github.com/repos/ebassi/graphene/issues/43/comments","events_url":"https://api.github.com/repos/ebassi/graphene/issues/43/events","html_url":"https://github.com/ebassi/graphene/issues/43","id":124771384,"number":43,"title":"Explain a bit more the underlying maths?","user":{"login":"swilmet","id":309393,"avatar_url":"https://avatars.githubusercontent.com/u/309393?v=3","gravatar_id":"","url":"https://api.github.com/users/swilmet","html_url":"https://github.com/swilmet","followers_url":"https://api.github.com/users/swilmet/followers","following_url":"https://api.github.com/users/swilmet/following{/other_user}","gists_url":"https://api.github.com/users/swilmet/gists{/gist_id}","starred_url":"https://api.github.com/users/swilmet/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/swilmet/subscriptions","organizations_url":"https://api.github.com/users/swilmet/orgs","repos_url":"https://api.github.com/users/swilmet/repos","events_url":"https://api.github.com/users/swilmet/events{/privacy}","received_events_url":"https://api.github.com/users/swilmet/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":2,"created_at":"2016-01-04T14:45:16Z","updated_at":"2016-01-05T12:18:48Z","closed_at":null,"body":"I'm finally learning computer graphics with the Fundamentals of Computer Graphics book, by Shirley and Marshner. In parallel I'm looking at the graphene API and implementation.\r\n\r\nI wonder if it makes sense to better explain the underlying maths in the graphene API. At least just a summary or examples.\r\n\r\nFor example for graphene_point_interpolate(), it could be explained that for a factor of 0 the result is the point a, for a factor of 1 it's the point b and 0.5 (for example) is at the middle of the line that goes through a and b.\r\n\r\nOr is it considered too well-known to bother explaining that kind of thing?"},"comment":{"url":"https://api.github.com/repos/ebassi/graphene/issues/comments/168984822","html_url":"https://github.com/ebassi/graphene/issues/43#issuecomment-168984822","issue_url":"https://api.github.com/repos/ebassi/graphene/issues/43","id":168984822,"user":{"login":"swilmet","id":309393,"avatar_url":"https://avatars.githubusercontent.com/u/309393?v=3","gravatar_id":"","url":"https://api.github.com/users/swilmet","html_url":"https://github.com/swilmet","followers_url":"https://api.github.com/users/swilmet/followers","following_url":"https://api.github.com/users/swilmet/following{/other_user}","gists_url":"https://api.github.com/users/swilmet/gists{/gist_id}","starred_url":"https://api.github.com/users/swilmet/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/swilmet/subscriptions","organizations_url":"https://api.github.com/users/swilmet/orgs","repos_url":"https://api.github.com/users/swilmet/repos","events_url":"https://api.github.com/users/swilmet/events{/privacy}","received_events_url":"https://api.github.com/users/swilmet/received_events","type":"User","site_admin":false},"created_at":"2016-01-05T12:18:48Z","updated_at":"2016-01-05T12:18:48Z","body":"I have other examples of functions where explaining the conventions used would be useful, at least as a reminder:\r\n- graphene_rect_union(): at first I didn't know what it does by just reading the API, and by reading the implementation I find it a bit strange.\r\n- graphene_triangle_get_barycoords(): u and v are on which axes? ab and ac, respectively?\r\n- graphene_triangle_get_midpoint(): explain where is the midpoint, exactly.\r\n\r\nFor interpolate(), 0 and 1 are just conventions. Maybe some old and less-well-known books use different conventions like -1 and 1 or whatever.\r\n\r\nAnyway I think this is best discussed concretely on a case-by-case basis, I can come up with some patches.\r\n\r\nBut another potential audience for Graphene is for people learning computer graphics, as a nice complementary for a book explaining the theory (at least for the first chapters): see in practice how computer graphics data types are represented on the computer, implementing a basic ray-tracer, etc."}}