Changeset 33100 in project


Ignore:
Timestamp:
01/20/16 07:50:50 (4 years ago)
Author:
John Croisant
Message:

sdl2: More 0.2.0 docs (renderer, miscellaneous).

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/4/sdl2

    r33098 r33100  
    459459
    460460
     461<procedure>(color->values color) → [r g b a]</procedure>
     462<procedure>(colour->values color) → [r g b a]</procedure>
     463
     464Returns multiple values containing the value of each field of the sdl2:color.
     465This is useful for destructuring an sdl2:color using {{receive}} or {{let-values}}.
     466
     467
    461468<procedure>(color=? color1 color2) → boolean</procedure>
    462469<procedure>(colour=? color1 color2) → boolean</procedure>
     
    19111918For more information see [[https://hg.libsdl.org/SDL/file/default/include/SDL_hints.h|SDL_hints.h]].
    19121919
    1913 Procedures for getting and setting hints is available in '''sdl2 egg version 0.2.0 and later'''.
     1920Procedures for getting and setting hints is available in '''sdl2 egg version 0.2.0 and higher'''.
    19141921But, SDL will notice environment variables even if you are using an earlier version of the sdl2 egg.
    19151922
     
    21462153Returns the current value of the hint as a string, or #f if the hint has no value.
    21472154See [[https://wiki.libsdl.org/SDL_GetHint|SDL_GetHint]].
    2148 This procedure is available in '''sdl2 egg version 0.2.0 and later'''.
     2155This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
    21492156
    21502157
     
    21532160Sets the value of the hint.
    21542161See [[https://wiki.libsdl.org/SDL_SetHintWithPriority|SDL_SetHintWithPriority]].
    2155 This procedure is available in '''sdl2 egg version 0.2.0 and later'''.
     2162This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
    21562163
    21572164{{name}} specifies which hint to change.
     
    21792186Removes the values and priorities of all hints.
    21802187See [[https://wiki.libsdl.org/SDL_ClearHints|SDL_ClearHints]].
    2181 This procedure is available in '''sdl2 egg version 0.2.0 and later'''.
     2188This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
    21822189
    21832190
     
    29012908
    29022909
     2910<procedure>(point-in-rect? point rect) → boolean</procedure>
     2911
     2912Returns #t if the sdl2:point is inside the sdl2:rect, or #f if it is not.
     2913See [[https://wiki.libsdl.org/SDL_PointInRects|SDL_PointInRect]].
     2914
     2915This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
     2916It requires '''SDL 2.0.4 or higher'''.
     2917It signals an error if the compiled version of SDL is not high enough.
     2918Use {{(version-at-least? 2 0 4)}} to check before calling this procedure.
     2919
     2920
    29032921<procedure>(enclose-points points #!optional clip result-rect) → [rect any-enclosed?]</procedure>
    29042922
     
    30483066
    30493067
     3068<procedure>(rect->values rect) → [x y w h]</procedure>
     3069
     3070Returns multiple values containing the value of each field of the sdl2:rect.
     3071This is useful for destructuring an sdl2:rect using {{receive}} or {{let-values}}.
     3072
     3073
    30503074<procedure>(rect=? rect1 rect2) → boolean</procedure>
    30513075
     
    31233147
    31243148
     3149<procedure>(point->values point) → [x y]</procedure>
     3150
     3151Returns multiple values containing the value of each field of the sdl2:point.
     3152This is useful for destructuring an sdl2:point using {{receive}} or {{let-values}}.
     3153
     3154
    31253155<procedure>(point=? point1 point2) → boolean</procedure>
    31263156
     
    31363166* {{copy-point}} returns a managed sdl2:point.
    31373167* {{copy-point*}} returns an unmanaged sdl2:point, which must be freed with {{free-point!}} when you are done with it.
     3168
     3169
     3170
     3171=== Renderer
     3172
     3173Renderer is one part of [[https://wiki.libsdl.org/CategoryRender|2D Accelerated Rendering]].
     3174See also [[#texture|Texture]].
     3175
     3176Renderer support is available in '''sdl2 egg 0.2.0 and higher'''.
     3177
     3178
     3179==== Renderer Functions
     3180
     3181<procedure>(create-renderer! window index #!optional flags) → sdl2:renderer</procedure>
     3182
     3183See [[https://wiki.libsdl.org/SDL_CreateRenderer|SDL_CreateRenderer]].
     3184This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
     3185
     3186
     3187<procedure>(create-software-renderer! surface) → sdl2:renderer</procedure>
     3188
     3189See [[https://wiki.libsdl.org/SDL_CreateSoftwareRenderer|SDL_CreateSoftwareRenderer]].
     3190This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
     3191
     3192
     3193<procedure>(destroy-renderer! renderer)</procedure>
     3194
     3195See [[https://wiki.libsdl.org/SDL_DestroyRenderer|SDL_DestroyRenderer]].
     3196This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
     3197
     3198
     3199<procedure>(create-window-and-renderer! width height #!optional window-flags) → [window renderer]</procedure>
     3200
     3201See [[https://wiki.libsdl.org/SDL_CreateWindowAndRenderer|SDL_CreateWindowAndRenderer]].
     3202This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
     3203
     3204{{width}} and {{height}} specify the height of the window to create.
     3205
     3206{{window-flags}} defaults to {{'()}}. It must be a list of zero or more [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#window-flags|window flag symbols]] (or an equivalent integer bitfield).
     3207
     3208This procedure returns multiple values:
     3209
     3210; window : The sdl2:window that was created.
     3211; renderer : The sdl2:renderer that was created.
     3212
     3213
     3214<procedure>(get-renderer window) → sdl2:renderer</procedure>
     3215
     3216See [[https://wiki.libsdl.org/SDL_GetRenderer|SDL_GetRenderer]].
     3217This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
     3218
     3219Signals an exception of kind {{(exn sdl2)}} if the window does not have a renderer,
     3220or if an error occurs.
     3221
     3222
     3223<procedure>(get-renderer-info renderer) → sdl2:renderer-info</procedure>
     3224<procedure>(get-renderer-info* renderer) → sdl2:renderer-info</procedure>
     3225
     3226See [[https://wiki.libsdl.org/SDL_GetRendererInfo|SDL_GetRendererInfo]].
     3227These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
     3228
     3229* {{get-renderer-info}} returns a managed sdl2:renderer-info.
     3230* {{get-renderer-info*}} returns an unmanaged sdl2:renderer-info, which must be freed using {{free-renderer-info!}} when you are done with it.
     3231
     3232
     3233<procedure>(num-render-drivers) → integer</procedure>
     3234
     3235See [[https://wiki.libsdl.org/SDL_GetNumRenderDrivers|SDL_GetNumRenderDrivers]].
     3236This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
     3237
     3238
     3239<procedure>(render-driver-info index) → sdl2:renderer-info</procedure>
     3240
     3241See [[https://wiki.libsdl.org/SDL_GetRenderDriverInfo|SDL_GetRenderDriverInfo]].
     3242This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
     3243
     3244
     3245<procedure>(render-present!)</procedure>
     3246
     3247See [[https://wiki.libsdl.org/SDL_RenderPresent|SDL_RenderPresent]].
     3248This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
     3249
     3250
     3251<procedure>(render-copy! renderer texture #!optional srcrect dstrect) → </procedure>
     3252
     3253See [[https://wiki.libsdl.org/SDL_RenderCopy|SDL_RenderCopy]].
     3254This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
     3255
     3256
     3257<procedure>(render-copy-ex! renderer texture #!optional srcrect dstrect angle center flip)</procedure>
     3258
     3259See [[https://wiki.libsdl.org/SDL_RenderCopyEx|SDL_RenderCopyEx]].
     3260This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
     3261
     3262
     3263<procedure>(render-target-supported? renderer) → boolean</procedure>
     3264
     3265See [[https://wiki.libsdl.org/SDL_RenderTargetSupported|SDL_RenderTargetSupported]].
     3266This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
     3267
     3268
     3269<procedure>(render-target renderer) → sdl2:texture or #f</procedure>
     3270<setter>(render-target-set! renderer target)</setter>
     3271<setter>(set! (render-target renderer) target)</setter>
     3272
     3273See [[https://wiki.libsdl.org/SDL_GetRenderTarget|SDL_GetRenderTarget]]
     3274and [[https://wiki.libsdl.org/SDL_SetRenderTarget|SDL_SetRenderTarget]].
     3275These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
     3276
     3277
     3278<procedure>(render-read-pixels-raw renderer rect format pixels-out pitch)</procedure>
     3279
     3280See [[https://wiki.libsdl.org/SDL_RenderReadPixels|SDL_RenderReadPixels]].
     3281This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
     3282
     3283
     3284<procedure>(render-draw-blend-mode renderer) → symbol</procedure>
     3285<procedure>(render-draw-blend-mode-raw renderer) → integer</procedure>
     3286<setter>(render-draw-blend-mode-set! renderer mode)</setter>
     3287<setter>(set! (render-draw-blend-mode renderer) mode)</setter>
     3288
     3289Get or set the renderer's draw blend mode. This affects future drawing operations.
     3290See [[https://wiki.libsdl.org/SDL_GetRenderDrawBlendMode|SDL_GetRenderDrawBlendMode]]
     3291and [[https://wiki.libsdl.org/SDL_SetRenderDrawBlendMode|SDL_SetRenderDrawBlendMode]].
     3292These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
     3293
     3294* {{render-draw-blend-mode}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#blend-mode|blend mode symbol]]:
     3295** {{'none}}
     3296** {{'blend}}
     3297** {{'add}}
     3298** {{'mod}}
     3299* {{render-draw-blend-mode-raw}} returns an integer.
     3300* The setters accept either a symbol or integer.
     3301
     3302
     3303<procedure>(render-draw-color renderer) → sdl2:color</procedure>
     3304<procedure>(render-draw-colour renderer) → sdl2:color</procedure>
     3305<setter>(render-draw-color-set! renderer color)</setter>
     3306<setter>(render-draw-colour-set! renderer color)</setter>
     3307<setter>(set! (render-draw-color renderer) color)</setter>
     3308<setter>(set! (render-draw-colour renderer) color)</setter>
     3309
     3310Get or set the renderer's draw color. This affects future drawing operations.
     3311See [[https://wiki.libsdl.org/SDL_GetRenderDrawColor|SDL_GetRenderDrawColor]]
     3312and [[https://wiki.libsdl.org/SDL_SetRenderDrawColor|SDL_SetRenderDrawColor]].
     3313These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
     3314
     3315
     3316<procedure>(render-clear! renderer)</procedure>
     3317
     3318Clear the entire renderer, using the renderer's current draw color.
     3319See [[https://wiki.libsdl.org/SDL_RenderClear|SDL_RenderClear]].
     3320This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
     3321
     3322
     3323<procedure>(render-draw-line! renderer x1 y1 x2 y2)</procedure>
     3324<procedure>(render-draw-lines! renderer points)</procedure>
     3325
     3326Draw a line segment or multiple connected line segments, using the renderer's current draw color and blend mode.
     3327See [[https://wiki.libsdl.org/SDL_RenderDrawLine|SDL_RenderDrawLine]]
     3328and [[https://wiki.libsdl.org/SDL_RenderDrawLines|SDL_RenderDrawLines]].
     3329These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
     3330
     3331* {{render-draw-line!}} draws a single line segment.
     3332* {{render-draw-lines!}} draws multiple connected line segments. {{points}} must be a list or vector of sdl2:point instances.
     3333
     3334
     3335<procedure>(render-draw-point! renderer x y)</procedure>
     3336<procedure>(render-draw-points! renderer points)</procedure>
     3337
     3338Draw one or multiple points, using the renderer's current draw color and blend mode.
     3339See [[https://wiki.libsdl.org/SDL_RenderDrawPoint|SDL_RenderDrawPoint]]
     3340and [[https://wiki.libsdl.org/SDL_RenderDrawPoints|SDL_RenderDrawPoints]].
     3341These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
     3342
     3343* {{render-draw-point!}} draws a single point.
     3344* {{render-draw-points!}} draws multiple points. {{points}} must be a list or vector of sdl2:point instances.
     3345
     3346
     3347<procedure>(render-draw-rect! renderer rect)</procedure>
     3348<procedure>(render-draw-rects! renderer rects)</procedure>
     3349
     3350Draw one or multiple outlined rectangles, using the renderer's current draw color and blend mode.
     3351See [[https://wiki.libsdl.org/SDL_RenderDrawRect|SDL_RenderDrawRect]]
     3352and [[https://wiki.libsdl.org/SDL_RenderDrawRects|SDL_RenderDrawRects]].
     3353These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
     3354
     3355* {{render-draw-rect!}} draws a single outlined rect.
     3356* {{render-draw-rects!}} draws multiple outlined rects. {{rects}} must be a list or vector of sdl2:rect instances.
     3357
     3358
     3359<procedure>(render-fill-rect! renderer rect)</procedure>
     3360<procedure>(render-fill-rects! renderer rects)</procedure>
     3361
     3362Draw one or multiple filled rectangles, using the renderer's current draw color and blend mode.
     3363See [[https://wiki.libsdl.org/SDL_RenderFillRect|SDL_RenderFillRect]]
     3364and [[https://wiki.libsdl.org/SDL_RenderFillRects|SDL_RenderFillRects]].
     3365These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
     3366
     3367* {{render-draw-rect!}} draws a single filled rect.
     3368* {{render-draw-rects!}} draws multiple filled rects. {{rects}} must be a list or vector of sdl2:rect instances.
     3369
     3370
     3371==== sdl2:renderer
     3372
     3373sdl2:renderer is a record type that wraps a pointer to an SDL_Renderer struct.
     3374sdl2:renderer is available in '''sdl2 egg version 0.2.0 and higher'''.
     3375
     3376
     3377<procedure>(renderer? obj) → boolean</procedure>
     3378
     3379Returns #t if {{obj}} is an sdl2:renderer.
     3380This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
     3381
     3382
     3383<procedure>(renderer-output-size renderer) → [w h]</procedure>
     3384
     3385See [[https://wiki.libsdl.org/SDL_GetRendererOutputSize|SDL_GetRendererOutputSize]].
     3386This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
     3387
     3388This procedure returns multiple values, the output width and height, as integers.
     3389
     3390
     3391<procedure>(render-clip-rect renderer) → sdl2:rect</procedure>
     3392<setter>(render-clip-rect-set! renderer rect)</setter>
     3393<setter>(set! (render-clip-rect renderer) rect)</setter>
     3394
     3395Get or set the sdl2:renderer's clip rect.
     3396See [[https://wiki.libsdl.org/SDL_RenderGetClipRect|SDL_RenderGetClipRect]]
     3397and [[https://wiki.libsdl.org/SDL_RenderSetClipRect|SDL_RenderSetClipRect]].
     3398These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
     3399
     3400{{render-clip-rect}} returns a new managed sdl2:rect describing the renderer's clip rect.
     3401Returns {{#<sdl2:rect (0 0 0 0)>}} if clipping is disabled.
     3402
     3403But, be aware that it also returns {{#<sdl2:rect (0 0 0 0)>}} if that is the current clip rect.
     3404Use {{render-clip-enabled?}} (in SDL 2.0.4 or higher) to unambiguously check whether clipping is enabled or disabled.
     3405
     3406The setters accept either an sdl2:rect to enable clipping and set the clip rect,
     3407or #f to disable clipping.
     3408
     3409
     3410<procedure>(render-clip-enabled? renderer) → boolean</procedure>
     3411
     3412Returns #t if clipping is enabled for the given sdl2:renderer,
     3413or #f is clipping is disabled.
     3414See [[https://wiki.libsdl.org/SDL_RenderIsClipEnabled|SDL_RenderIsClipEnabled]].
     3415
     3416This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
     3417It requires '''SDL 2.0.4 or higher'''.
     3418It signals an error if the compiled version of SDL is not high enough.
     3419Use {{(version-at-least? 2 0 4)}} to check before calling this procedure.
     3420
     3421
     3422<procedure>(render-logical-size renderer) → [w h]</procedure>
     3423<setter>(render-logical-size-set! renderer size)</setter>
     3424<setter>(set! (render-logical-size renderer) size)</setter>
     3425
     3426Get or set the renderer's logical size.
     3427See [[https://wiki.libsdl.org/SDL_RenderGetLogicalSize|SDL_RenderGetLogicalSize]]
     3428and [[https://wiki.libsdl.org/SDL_RenderSetLogicalSize|SDL_RenderSetLogicalSize]].
     3429These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
     3430
     3431* {{render-logical-size}} returns multiple values, the logical width and height, as integers.
     3432* The setters accept a list {{(w h)}} containing the new logical width and height, as integers.
     3433
     3434
     3435<procedure>(render-scale renderer) → [x-scale y-scale]</procedure>
     3436<setter>(render-scale-set! renderer scales)</setter>
     3437<setter>(set! (render-scale-set! renderer) scales)</setter>
     3438
     3439Get or set the sdl2:renderer's x and y scaling factors.
     3440See [[https://wiki.libsdl.org/SDL_RenderGetScale|SDL_RenderGetScale]]
     3441and [[https://wiki.libsdl.org/SDL_RenderSetScale|SDL_RenderSetScale]].
     3442These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
     3443
     3444* {{render-scale}} returns multiple values, the x and y scaling factors, as integers..
     3445* The setters accept a list {{(x-scale y-scale)}} containing the new scaling factors, as integers.
     3446
     3447
     3448<procedure>(render-viewport renderer) → sdl2:rect</procedure>
     3449<setter>(render-viewport-set! renderer rect)</setter>
     3450<setter>(set! (render-viewport renderer) rect)</setter>
     3451
     3452Get or set the renderer's viewport.
     3453See [[https://wiki.libsdl.org/SDL_RenderGetViewport|SDL_RenderGetViewport]]
     3454and [[https://wiki.libsdl.org/SDL_RenderSetViewport|SDL_RenderSetViewport]].
     3455These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
     3456
     3457
     3458
     3459==== sdl2:renderer-info
     3460
     3461sdl2:renderer-info is a record type that wraps a pointer to an
     3462[[https://wiki.libsdl.org/SDL_RendererInfo|SDL_RendererInfo]] struct.
     3463sdl2:renderer-info is available in '''sdl2 egg version 0.2.0 and higher'''.
     3464
     3465<procedure>(renderer-info? obj) → boolean</procedure>
     3466
     3467Returns #t if {{obj}} is an sdl2:renderer-info.
     3468This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
     3469
     3470
     3471<procedure>(free-renderer-info! renderer-info)</procedure>
     3472
     3473Free the memory of the sdl2:renderer-info's underlying struct.
     3474{{renderer-info}}'s pointer will be set to null (see {{struct-null?}}).
     3475It is safe to call this procedure with managed or unmanaged sdl2:renderer-infos.
     3476It is safe (but has no effect) to free a struct record multiple times.
     3477This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
     3478
     3479
     3480<procedure>(renderer-info-name renderer-info) → string</procedure>
     3481
     3482Get the sdl2:renderer-info's "name" field, as a string.
     3483This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
     3484
     3485
     3486<procedure>(renderer-info-flags renderer-info) → list of symbols</procedure>
     3487<procedure>(renderer-info-flags-raw renderer-info) → integer</procedure>
     3488
     3489Get the sdl2:renderer-info's "flags" field, as a list of symbols or an integer.
     3490TODO: Link to flags enums.
     3491These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
     3492
     3493
     3494<procedure>(renderer-info-num-texture-formats renderer-info) → integer</procedure>
     3495
     3496Get the sdl2:renderer-info's "num-texture-formats" field, as an integer.
     3497This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
     3498
     3499
     3500<procedure>(renderer-info-texture-formats renderer-info) → list of symbols</procedure>
     3501
     3502Get the sdl2:renderer-info's "texture-formats" field,
     3503as a list of [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#pixel-formats|pixel format symbols]].
     3504This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
     3505
     3506
     3507<procedure>(renderer-info-max-texture-width renderer-info) → integer</procedure>
     3508
     3509Get the sdl2:renderer-info's "max-texture-width" field, as an integer.
     3510This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
     3511
     3512
     3513<procedure>(renderer-info-max-texture-height renderer-info) → integer</procedure>
     3514
     3515Get the sdl2:renderer-info's "max-texture-height" field, as an integer.
     3516This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
    31383517
    31393518
     
    38334212* {{'mouse-focus}}
    38344213* {{'foreign}}
     4214* {{'allow-high-dpi}} (requires '''sdl2 egg 0.2.0 and SDL 2.0.1 or higher''')
     4215* {{'mouse-capture}} (requires '''sdl2 egg 0.2.0 and SDL 2.0.4 or higher''')
    38354216
    38364217
Note: See TracChangeset for help on using the changeset viewer.