{"action":"created","issue":{"url":"https://api.github.com/repos/SFML/SFML/issues/846","labels_url":"https://api.github.com/repos/SFML/SFML/issues/846/labels{/name}","comments_url":"https://api.github.com/repos/SFML/SFML/issues/846/comments","events_url":"https://api.github.com/repos/SFML/SFML/issues/846/events","html_url":"https://github.com/SFML/SFML/pull/846","id":64657889,"number":846,"title":"Added support for clipping masks (Implements #1)","user":{"login":"zsbzsb","id":3647990,"avatar_url":"https://avatars.githubusercontent.com/u/3647990?v=3","gravatar_id":"","url":"https://api.github.com/users/zsbzsb","html_url":"https://github.com/zsbzsb","followers_url":"https://api.github.com/users/zsbzsb/followers","following_url":"https://api.github.com/users/zsbzsb/following{/other_user}","gists_url":"https://api.github.com/users/zsbzsb/gists{/gist_id}","starred_url":"https://api.github.com/users/zsbzsb/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/zsbzsb/subscriptions","organizations_url":"https://api.github.com/users/zsbzsb/orgs","repos_url":"https://api.github.com/users/zsbzsb/repos","events_url":"https://api.github.com/users/zsbzsb/events{/privacy}","received_events_url":"https://api.github.com/users/zsbzsb/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/SFML/SFML/labels/feature","name":"feature","color":"23BA35"},{"url":"https://api.github.com/repos/SFML/SFML/labels/m:sfml-graphics","name":"m:sfml-graphics","color":"cccccc"},{"url":"https://api.github.com/repos/SFML/SFML/labels/s:undecided","name":"s:undecided","color":"ffe20a"}],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":35,"created_at":"2015-03-26T23:47:22Z","updated_at":"2016-01-01T14:40:01Z","closed_at":null,"pull_request":{"url":"https://api.github.com/repos/SFML/SFML/pulls/846","html_url":"https://github.com/SFML/SFML/pull/846","diff_url":"https://github.com/SFML/SFML/pull/846.diff","patch_url":"https://github.com/SFML/SFML/pull/846.patch"},"body":"*Recreated from #842*\r\n\r\nThis is ready for a code review, hoping for a SFML 2.4 inclusion. This implements #1, yes the very first issue. :smile:\r\n\r\nI based my branch on /feature/gl_dev_new due to the OpenGL changes. Clipping is done with the stencil buffer which gets enabled when a mask is applied to the render states.\r\n\r\nSome points from #1 are answered below about this implementation.\r\n\r\n>And do we clip in scene coordinates or in window coordinates?\r\n\r\nClipping is done in scene coordinates.\r\n\r\n>However since it can be disabled (and is currently not enabled by default) in the context settings.\r\n\r\nIt is now enabled by default in the context and render texture constructors.\r\n\r\n>it implies that the user can disable clipping masks, without even knowing it. So this must be at least well documented, and even enforced if possible.\r\n\r\nIt is now noted in the documentation that disabling stencil buffer will disable clipping masks. As for enforcing it? Its not really needed, if the user disables it - it is their fault because it is clearly stated.\r\n\r\n>So the main problem is to decide what we use to define the clipping area. We could start with a ```const sf::Drawable*``` to have maximum flexibility.\r\n\r\nClipping area is defined by the ```sf::ClippingMask``` class which is a container for multiple ```const sf::Drawable*``` pointers.\r\n\r\n>Another question is: do we allow only one active mask, or do we provide the ability to add multiple masks?\r\n\r\nOnly 1 mask is active at one time, but it can be defined by multiple drawables.\r\n\r\nAs with my other PR (#840), please review and test and then give feedback. **Even textures with alpha channels are supported.**\r\n\r\n```cpp\r\n#include <SFML/Graphics.hpp>\r\n\r\nint main()\r\n{\r\n    sf::RenderWindow window({ 800, 600 }, \"Clipping Mask Test\");\r\n    window.setVerticalSyncEnabled(true);\r\n\r\n    // create a circle for part of the clipping mask\r\n    sf::CircleShape keyholetop(50);\r\n    keyholetop.setOrigin({ 50, 50 });\r\n\r\n    // create a square for part of the clipping mask\r\n    sf::RectangleShape keyholebody({ 36, 150 });\r\n    keyholebody.setOrigin({ 18, 0 });\r\n\r\n    // create the clipping mask\r\n    sf::ClippingMask clipmask;\r\n\r\n    // add the shapes to the clipping mask\r\n    // sf::ClippingMask behaves like sf::VertexArray\r\n    // so you can append any sf::Drawable to the mask\r\n    // the mask will not copy the sf::Drawable, it only stores a pointer\r\n    clipmask.append(keyholetop);\r\n    clipmask.append(keyholebody);\r\n\r\n    sf::Texture background;\r\n    // use any background image\r\n    // I used the image from opengl example\r\n    background.loadFromFile(\"sfml/examples/opengl/resources/background.jpg\");\r\n\r\n    sf::Sprite backgroundsprite(background);\r\n\r\n    // set a clipping area\r\n    // for this example exlude the area 50px from the borders\r\n    window.setClippingArea({ 50, 50, 700, 500 });\r\n\r\n    while (window.isOpen())\r\n    {\r\n        sf::Event e;\r\n        while (window.pollEvent(e))\r\n        {\r\n            if (e.type == sf::Event::Closed)\r\n                window.close();\r\n        }\r\n\r\n        // get mouse position\r\n        sf::Vector2f mousepos = window.mapPixelToCoords(sf::Mouse::getPosition(window));\r\n\r\n        // update the mask position\r\n        clipmask.setPosition(mousepos);\r\n\r\n        //assign the clipping mask to the window\r\n        window.setClippingMask(clipmask);\r\n\r\n        window.clear(sf::Color::Blue);\r\n\r\n        window.draw(backgroundsprite);\r\n\r\n        window.display();\r\n    }\r\n}\r\n```\r\n\r\n![Example Screenshot](http://i.imgur.com/u2iKBwd.png)\r\n\r\n\r\n-------------------------------------------------------------------------------------------\r\n\r\n\r\nI just updated the API. I removed the clipping mask from the render states and instead added function the render target class for setting the mask. Also all clipping is now cached instead of redrawn every time.\r\n\r\nAnd I will say it again: **Please test and give feedback - even if you don't test this branch, at least comment on the API design, thanks** :smile: \r\n\r\nThere was a total of 6 functions added to the render target class.\r\n\r\n```\r\nclearClipping[Area|Mask]();\r\nsetClipping[Area|Mask](...);\r\ngetClipping[Area|Mask]();\r\n```\r\n\r\nClipping masks are the same as the previous commits, basically a list of drawables that allow users to define custom shapes / pixel based masks. The masks are implemented with the stencil buffer.\r\n\r\nClipping areas on the other hand are limited to a single IntRect that is defined in window coordinates. The clipping area is implemented using ```glScissor(...)``` which should provide faster, simpler clipping for those who just need it for basic GUIs.\r\n\r\nThe clipping mask on the other hand is heavier and uses the stencil buffer for clipping. It works in scene coordinates and is used for more complex masks.\r\n\r\nBoth clipping modes are applied like the view is. To set a clipping mode you first call ```setClippingXXX(...)``` with the appropriate parameters. The clipping mode will be cached until it is either cleared or updated (another set call).\r\n"},"comment":{"url":"https://api.github.com/repos/SFML/SFML/issues/comments/168311301","html_url":"https://github.com/SFML/SFML/pull/846#issuecomment-168311301","issue_url":"https://api.github.com/repos/SFML/SFML/issues/846","id":168311301,"user":{"login":"Bromeon","id":708488,"avatar_url":"https://avatars.githubusercontent.com/u/708488?v=3","gravatar_id":"","url":"https://api.github.com/users/Bromeon","html_url":"https://github.com/Bromeon","followers_url":"https://api.github.com/users/Bromeon/followers","following_url":"https://api.github.com/users/Bromeon/following{/other_user}","gists_url":"https://api.github.com/users/Bromeon/gists{/gist_id}","starred_url":"https://api.github.com/users/Bromeon/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Bromeon/subscriptions","organizations_url":"https://api.github.com/users/Bromeon/orgs","repos_url":"https://api.github.com/users/Bromeon/repos","events_url":"https://api.github.com/users/Bromeon/events{/privacy}","received_events_url":"https://api.github.com/users/Bromeon/received_events","type":"User","site_admin":false},"created_at":"2016-01-01T14:40:01Z","updated_at":"2016-01-01T14:40:01Z","body":"Remarks on my [previous comment](https://github.com/SFML/SFML/pull/846#issuecomment-137665573)?"}}