Code Improvements and Documentation Enhancements for OSLib

[dogo]

Summary

This PR introduces several code improvements and documentation enhancements to the OSLib codebase, focusing on better code clarity, maintainability, and performance. Key changes include the addition of inline setter functions for image flags, improved documentation for low-level drawing functions, and the introduction of vertex types for optimized rendering.

Changes

1. Image Flag Management:

   • Added inline setter functions for managing image flags such as oslImageIsCopySet, oslImageIsSwizzledSet, and oslImageSetAutoStrip. These functions improve code readability and encapsulate flag manipulation, reducing the risk of errors.
   • Updated macros for checking image flags, such as oslImageIsCopy, oslImageIsSwizzled, and oslImageGetAutoStrip.

2. Texturing Functions:

   • Improved the oslEnableTexturing and oslDisableTexturing macros to better manage the state of texturing, ensuring that redundant state changes are avoided.
   • Documented the usage of OSL_SLICE_SIZE and provided guidance on handling image strips when drawing large images.

3. Texture Wrapping:

   • Introduced oslSetTextureWrap to manage texture wrapping behavior, allowing textures to be repeated or clamped based on user-defined parameters. This change provides a clearer and more controlled way to manage texture behavior when rendering beyond texture bounds.

4. Low-Level Drawing Functions:

   • Enhanced the documentation for low-level drawing functions, including detailed explanations and code examples for both textured and untextured object rendering.
   • Added documentation and structured typedefs for various vertex types (OSL_PRECISE_VERTEX, OSL_FAST_VERTEX, OSL_FAST_VERTEX_COLOR32, OSL_LINE_VERTEX, OSL_LINE_VERTEX_COLOR32, and OSL_UVFLOAT_VERTEX). These vertex types offer different trade-offs between precision and performance, improving the efficiency of rendering operations.

5. Internal State Management:

   • Documented and marked internal variables (osl_curTexture, osl_curPalette, osl_curDrawBuf, etc.) as internal use only, discouraging external use to prevent misuse and ensure the integrity of internal state management.

6. Miscellaneous:

   • Updated various undocumented or deprecated functions and structures to clarify their intended usage and discourage their use outside of specific internal contexts.
   • Improved overall documentation, ensuring that every public function is well-documented with clear examples where applicable.

Impact

These changes improve the robustness, clarity, and performance of the OSLib codebase, making it easier for developers to understand and use the library effectively. The enhanced documentation and code organization will also facilitate future development and maintenance efforts.

Testing

• Verified that all image flag manipulation functions work correctly and that texturing functions manage states efficiently.
• Tested low-level drawing functions to ensure they produce the expected results using different vertex types.
• Confirmed that internal variables and states are handled correctly without any unintended side effects.