Added example for toImageSync + setImageSampler

[gaaclarke]

Description of what this PR is changing or adding, and why:

Adds more clarity about how to chain together fragment shaders.

Issues fixed by this PR (if any):

fixes flutter/flutter#177133

PRs or commits this PR depends on (if any):

Presubmit checklist

• If you are unwilling, or unable, to sign the CLA, even for a tiny, one-word PR, please file an issue instead of a PR.
• If this PR is not meant to land until a future stable release, mark it as draft with an explanation.
• This PR follows the Google Developer Documentation Style Guidelines—for example, it doesn't use i.e. or e.g., and it avoids I and we (first-person pronouns).
• This PR uses semantic line breaks
  of 80 characters or fewer.

[gemini-code-assist]

Summary of Changes

Hello @gaaclarke, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request enhances the documentation for fragment shaders by providing practical examples of how to chain them together. The primary goal is to offer clearer guidance on using Picture.toImageSync to capture a shader's output as an image and then feeding that image into another shader via FragmentShader.setImageSampler, thereby demonstrating advanced shader composition techniques.

Highlights

• Documentation Update: Added new examples to the fragment-shaders.md documentation to clarify the usage of toImageSync and setImageSampler.
• GLSL Sampler Example: Introduced a new section demonstrating sampler usage within GLSL, providing context for chaining shaders.
• Dart toImageSync Example: Included a comprehensive Dart code example featuring a CustomPainter that illustrates how to chain fragment shaders using Picture.toImageSync and FragmentShader.setImageSampler.
• Heading Level Adjustments: Updated the heading levels for 'Performance considerations' and 'Other resources' for better document structure.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request adds an example demonstrating how to use toImageSync to generate an image from one shader and use it as a sampler in another shader. This is a valuable addition for clarifying how to chain shaders. My review focuses on improving the example code to align with Flutter's best practices for CustomPainter, specifically regarding state management and performance, to ensure the documentation provides a high-quality and efficient code sample.

[flar]

This is more of a workaround than a fix for the cited issue. The work flow can be done - manually - with today's technology. But the issue that it claims it "fixes" is that users want to be able to just chain them together without having all of the glue code, isn't it?

[flutter-website-bot]

Visit the preview URL for this PR (updated for commit 6be2e2d):

https://flutter-docs-prod--pr12686-chain-fragment-shaders-wa72cm4t.web.app

[sfshaza2]

This looks ok to me. @gaaclarke, can you address the bot's and @flar's feedback?

[gaaclarke]

This is more of a workaround than a fix for the cited issue. The work flow can be done - manually - with today's technology. But the issue that it claims it "fixes" is that users want to be able to just chain them together without having all of the glue code, isn't it?

No, it was about adding the ability to do it. It was based on my ignorance and looking at the code of people doing liquid glass. Hopefully this example avoids that for people going forward.

[sfshaza2]

This lgtm, but I will wait for @flar to weigh in.